# JWT retrieve alias

Securely retrieve alias details using a **JWT-based authentication mechanism**. This process involves three key steps:

1. Creating a private alias with a `jwt_secret`.
2. Signing a JWT token with user-specific claims.
3. Using the token to access protected alias details.

### Step 1: Create a Private Alias

Create a private alias and assign it a `jwt_secret`. This secret will later be used to sign JWT tokens that authorize access to the alias.

**Endpoint:**

```
POST /organization/api/v1/alias/create
```

**URL:**

```
https://link.api.datagram.network/organization/api/v1/alias/create
```

#### **Request Body**

| Parameter       | Type    | Required | Description                                | Examp                                                       |
| --------------- | ------- | -------- | ------------------------------------------ | ----------------------------------------------------------- |
| **type**        | string  | ✅ Yes    | Type of alias                              | `"conference"`or `"live"`                                   |
| **name**        | string  | ❌ No     | Custom alias name                          | `"Team Sync Alias"`                                         |
| **jwt\_secret** | string  | ✅ Yes    | Secret used for signing JWT tokens         | <p><code>"myJWTsecret123"</code></p><p>"myJWTsecret123"</p> |
| **expired\_at** | integer | ✅ Yes    | Expiry time as Unix timestamp (in seconds) | `1737456308`                                                |

#### **Example Request**

```
{
  "type": "conference",
  "name": "Private Alias Name",
  "jwt_secret": "your-secure-secret",
  "expired_at": 1737456308
}
```

#### **Responses**

✅ **200 OK**

Alias successfully created.

| Field           | Type    | Description                     | Example                        |
| --------------- | ------- | ------------------------------- | ------------------------------ |
| **id**          | string  | Alias ID                        | "`alias_2XH5gT8vKp"`           |
| **type**        | string  | Alias type (conference or live) | `"conference"`                 |
| **name**        | string  | Name of the alias               | `"Q3 Product Launch"`          |
| **passcode**    | string  | Passcode if set (nullable)      | `null` or `"Pr0d!2024"`        |
| **jwt\_secret** | string  | The JWT signing secret          | `"sec_abc123...xyz456"`        |
| **stream\_key** | string  | Streaming key (nullable)        | `null`or `"live_2XH5gT8vKp"`   |
| **expired\_at** | integer | Expiry time of the alias        | `1735689600000` (Dec 31, 2024) |

#### **Example Response**

```
{
  "data": {
    "id": "priva",
    "type": "conference",
    "name": "Private Alias Name",
    "passcode": null,
    "jwt_secret": "your-secure-secret",
    "stream_key": null,
    "expired_at": 1737456308
  }
}
```

#### ❌ 401 Unauthorized

| Field       | Type   | Description                      | Example          |
| ----------- | ------ | -------------------------------- | ---------------- |
| **message** | string | Error message for invalid access | `"UNAUTHORIZED"` |

**Example**

```
{
  "error": {
    "message": "UNAUTHORIZED"
  }
}
```

❌ 404 Not Found

| Field       | Type   | Description                   | Example             |
| ----------- | ------ | ----------------------------- | ------------------- |
| **message** | string | Error when alias is not found | `"Alias not found"` |

**Example**

```
{
  "error": {
    "message": "Alias not found"
  }
}
```

### Step 2: Generate and Sign a JWT Token

Generate a JWT token using the alias's `jwt_secret` and user-specific claims.

**Example JWT Claims**

```
{
  "alias": "priva",
  "user_id": "user456xxyz",
  "host": true,
  "expires_in": 3600
}
```

| Claim           | Type    | Description                                      | Example           |
| --------------- | ------- | ------------------------------------------------ | ----------------- |
| **alias**       | string  | The ID of the alias being accessed               | `"alias123abc"`   |
| **user\_id**    | string  | Unique ID for the user                           | `"user789xyz"`    |
| **host**        | boolean | Indicates whether the user has host privileges   | `true` or `false` |
| **expires\_in** | integer | Token expiration time (in seconds from issuance) | `3600`            |

#### **Token Signing (Elixir Example)**

```
alias_id = "priva"
jwt_secret = "your-secure-secret"

claims = %{
  "alias" => alias_id,
  "user_id" => "user456xxyz",
  "host" => true,
  "expires_in" => 3600
}

{:ok, token, _} = JWT.generate_and_sign(claims, signer(jwt_secret))
```

### Step 3: Authenticate and Retrieve Alias

Use the generated token to retrieve alias details securely.

**Endpoint:**

```
GET /api/v1/alias/:id
```

**URL:**

```
https://link.api.datagram.network/api/v1/alias/priva
```

#### **Headers**

| Header            | Type   | Required | Description                  | Example                                 |
| ----------------- | ------ | -------- | ---------------------------- | --------------------------------------- |
| **authorization** | string | ✅ Yes    | Bearer token with signed JWT | `BearereyJhbGciOiJlUzl1NilslnR5cCl6...` |

#### **Example Request**

```
GET /api/v1/alias/priva HTTP/1.1
Host: link.api.datagram.network
Authorization: Bearer <jwt_token>
```

#### **Example Response**

```
{
  "data": {
    "id": "priva",
    "type": "conference",
    "name": "Private Alias Name",
    "passcode": null,
    "jwt_secret": null,
    "stream_key": null,
    "expired_at": 1737456308,
    "inserted_at": 1737356308
  }
}
```

### JWT Verification and Validation

The API performs the following steps to verify the JWT token:

1. Extract the JWT from the Authorization header.
2. Decode using the alias's jwt\_secret.
3. Validate claims:

* alias in the token matches the alias ID in the path.
* expires\_in is still valid (token not expired).

### Responses

| Code    | Description                                    | Example                                          |
| ------- | ---------------------------------------------- | ------------------------------------------------ |
| **200** | Successfully authenticated and alias retrieved | `{"alias" : "alias123abc", "status" : "active"}` |
| **401** | Unauthorized – Invalid or expired token        | `{"error": "unauthorized"}`                      |
| **404** | Alias not found                                | `{"error": "Alias not found"}`                   |

**401 Unauthorized Example**

```
{
  "error": {
    "message": "UNAUTHORIZED"
  }
}
```

**404 Not Found Example**

```
{
  "error": {
    "message": "Alias not found"
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.datagram.network/apis/api-reference/alias/jwt-retrieve-alias.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.