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	"myJWTsecret123" "myJWTsecret123"
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)	nullor "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"
  }
}