# 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"
  }
}
```