Datagram SDK

Appearance

API Documentation ​

Base URL ​

  • Production: https://link.api.datagram.network
  • Staging: https://link-staging.api.datagram.network

General Information ​

  • All endpoints are versioned under /api/v1 or /organization/api/v1.
  • Authentication is required for all /organization/api/v1 endpoints.
  • Requests and responses use JSON format unless otherwise specified.

Endpoints ​

1. Retrieve Alias by ID ​

GET /api/v1/alias/:id

Retrieve details for a specific alias using its ID.

Parameters: ​

  • Path Parameters:
    • id (string): The ID of the alias to retrieve.
  • Query Parameters:
    • passcode (string, optional): The passcode of the alias to retrieve.

Response: ​

  • Response Code:
    • 200 OK: Alias details retrieved successfully.
    • 400 Bad request: Alias not found / Unauthorized.
  • Response Value:
    • id (string): Alias ID.
    • type (string): Alias type ("live", "conference").
    • name (string, optional): Alias name.
    • passcode (string, optional): Alias passcode to basic authentication.
    • jwt_secret (string, optional): Alias jwt secret to advanced authentication.
    • stream_key (string, optional): Alias stream key.
    • expired_at (integer): Expired time unix timestamp in second.
    • inserted_at (integer): Inserted time unix timestamp in second.

Authentication: ​

  • Use a valid organization token in the Authorization header or Bearer jwt token match with jwt secret.
  • Example: Authorization: <token, optional>.

Example Request: ​

http
GET /api/v1/alias/12345 HTTP/1.1
Host: link.api.datagram.network
Authorization: <token, optional>

Example Response: ​

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

2. List All Aliases ​

GET /organization/api/v1/aliases

Retrieve a list of all aliases for the authenticated organization.

Parameters: ​

  • Query Parameters:
    • type (string): The type of the alias ("live", "conference").
    • after (string, optional): The cursor parameters.

Response: ​

  • Response Code:
    • 200 OK: Aliases listed successfully.
    • 401 Unauthorized: Unauthorized.
  • Response Value:
    • after (string, optional): The cursor parameters.
    • entries (list): List of alias.

Example Request: ​

http
GET /organization/api/v1/aliases HTTP/1.1
Host: link.api.datagram.network
Authorization: <token>

Example Response: ​

json
{
  "after": "after page",
  "entries": [{
      "data": {
        "id": "12345",
        "type": "conference",
        "name": "Alias Name",
        "passcode": null,
        "jwt_secret": null,
        "stream_key": null,
        "expired_at": 1737356308,
        "expired_at": 1737456308
      }
    }
  ]
}

3. Create Alias ​

POST /organization/api/v1/alias/create

Create a new alias for the authenticated organization.

Request Body: ​

  • type (string): The type of the alias ("live", "conference").
  • name (string, optional): Alias name.
  • passcode (string, optional): Alias passcode to basic authentication.
  • jwt_secret (string, optional): Alias jwt secret to advanced authentication.
  • stream_key (string, optional): Alias stream key.
  • expired_at (integer): Expired time unix timestamp in second.

Example Request: ​

http
POST /organization/api/v1/alias/create HTTP/1.1
Host: link.api.datagram.network
Authorization: <token>
Content-Type: application/json

{
  "type": "live",
  "name": "New Alias Name",
  "passcode": "pass",
  "jwt_secret": null,
  "stream_key": null,
  "expired_at": 1737456308
}

Example Response: ​

json
{
  "data": {
    "id": "xxyzx",
    "type": "live",
    "name": "New Alias Name",
    "passcode": "pass",
    "jwt_secret": null,
    "stream_key": null,
    "expired_at": 1737356308,
    "expired_at": 1737456308
  }
}

Response Codes: ​

  • 201 Created: Alias created successfully.
  • 400 Bad Request: Invalid request body.
  • 401 Unauthorized: Unauthorized.

4. Update Alias ​

POST /organization/api/v1/alias/update/:id

Update an existing alias.

Parameters: ​

  • Path Parameters:
    • id (string): The ID of the alias to update.

Request Body: ​

  • type (string): The type of the alias ("live", "conference").
  • name (string, optional): Alias name.
  • passcode (string, optional): Alias passcode to basic authentication.
  • jwt_secret (string, optional): Alias jwt secret to advanced authentication.
  • stream_key (string, optional): Alias stream key.
  • expired_at (integer): Expired time unix timestamp in second.

Example Request: ​

http
POST /organization/api/v1/alias/update/xxyzx HTTP/1.1
Host: link.api.datagram.network
Authorization: <token>
Content-Type: application/json

{
  "type": "conference",
  "name": "Updated Alias Name",
  "passcode": null
}

Example Response: ​

json
{
  "data": {
    "id": "xxyzx",
    "type": "conference",
    "name": "Updated Alias Name",
    "passcode": null,
    "jwt_secret": null,
    "stream_key": null,
    "expired_at": 1737356308,
    "expired_at": 1737456308
  }
}

Response Codes: ​

  • 200 OK: Alias updated successfully.
  • 400 Bad Request: Invalid request body or missing parameters / Alias not found.
  • 401 Unauthorized: Unauthorized.

5. Delete Alias ​

DELETE /organization/api/v1/alias/delete/:id

Delete an alias by its ID.

Parameters: ​

  • Path Parameters:
    • id (string): The ID of the alias to delete.

Example Request: ​

http
DELETE /organization/api/v1/alias/delete/12345 HTTP/1.1
Host: link.api.datagram.network
Authorization: Bearer <token>

Example Response: ​

json
{
  "message": "Alias deleted successfully."
}

Response Codes: ​

  • 200 OK: Alias deleted successfully.
  • 404 Not Found: Alias not found.
  • 401 Unauthorized: Unauthorized.

This documentation provides a clear understanding of how to interact with the API. Let me know if you need further details or adjustments!

JWT retrieve alias ​

Here’s the detailed continuation for JWT Retrieve Alias that incorporates the process of creating a private alias with a JWT secret, signing a JWT token with specific claims, and authenticating using the token.

JWT Retrieve Alias with Authentication ​

Step 1: Create a Private Alias

When creating a private alias, the organizer provides a jwt_secret. This secret is used to sign JWT tokens for users who need to authenticate and access the alias.

Endpoint:
POST /organization/api/v1/alias/create

Request Body: ​

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

Example Response: ​

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

Step 2: Generate and Sign a JWT Token

Once the alias is created, the organizer generates a JWT token for a user with claims that define their access. This token is signed using the alias's jwt_secret.

Example JWT Claims: ​

json
{
  "alias": "priva",
  "user_id": "user456xxyz",
  "host": true,
  "expires_in": 3600
}
  • alias: The ID of the alias.
  • user_id: A unique identifier for the user.
  • host: Boolean indicating if the user has host access.
  • expires_in: Token expiration time in seconds.

Signing the Token: ​

Use HS256 for signing the token with the jwt_secret:

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

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

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

Step 3: Authenticate with the JWT Token

To retrieve the alias details, the user must authenticate with the signed JWT token.

Endpoint:
GET /api/v1/alias/:id

Headers: ​

  • Authorization: Bearer <jwt_token>

Example Request: ​

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

Example Response: ​

json
{
  "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 verifies and validates the JWT token using the alias's jwt_secret. This ensures that:

  1. The token is signed with the correct secret.
  2. The claims match the alias's configuration.
  3. The token has not expired (expires_in claim).

Verification Steps: ​

  • Extract the token from the Authorization header.
  • Decode the token using the jwt_secret.
  • Validate the claims:
    • The alias matches the alias ID.
    • The expires_in timestamp is in the future.

Response Codes: ​

  • 200 OK: Successfully authenticated and alias details retrieved.
  • 401 Unauthorized: Invalid or expired JWT token.
  • 404 Not Found: Alias not found.

This process ensures secure and controlled access to private aliases using JWT authentication. Let me know if additional examples or clarifications are needed!