Skip to main content

​
Overview

The Unpod SDK needs an access token to connect to the server successfully. This token holds the participant’s identity, room name, capabilities, and permissions. Tokens are signed with your API secret to block forgery, and include an expiration time after which the server rejects them.
Expiration time only impacts the initial connection, and not subsequent reconnects.

​
Authentication Method

The Unpod API uses API Key Authentication:
HeaderFormatExample
AuthorizationToken <token>Authorization: Token a1b2c3d4e5f6g7h8i9j0...

​
How to Get Your API Token

Follow these steps to obtain your API token from the Unpod Dashboard:
  1. Login to the Unpod Dashboard
  2. After login, you’ll be redirected to the Hub page
  3. On the left sidebar, click on the Key icon (Api Keys)
  4. You’ll be redirected to the API Keys page
  5. Click Generate New API Key
  6. Copy and securely store your API token
If you delete an API key, you can always generate a new one from the API Keys page.

​
Error Responses

​
401 - Unauthorized

Returned when authentication credentials are missing or invalid. 
{
  "status_code": 401,
  "message": "Authentication credentials were not provided."
}

​
403 - Forbidden

Returned when the token is expired or access is denied. 
{
  "status_code": 403,
  "message": "Token has expired."
}

​
400 - Bad Request

Returned when required headers are missing. 
{
  "status_code": 400,
  "message": "Org-Handle header is required."
}

​
How to Get Your Organization Handle

Follow these steps to obtain your Organization Handle from the Unpod Dashboard:
  1. Login to the Unpod Dashboard
  2. On the left sidebar, click on the Studio View
  3. On the right sidebar, click on the Setting Icon
  4. You will see the Copy Org Handle option
  5. Click on it to copy the Organization Handle
The Organization Handle is required in the Org-Handle header for many API endpoints.

​
How to Get Your Space Token

Follow these steps to obtain your Space Token from the Unpod Dashboard:
  1. Login to the Unpod Dashboard
  2. On the left sidebar, click on the Conversation tab
  3. Click on the Settings icon
  4. You’ll see the Space Token option
  5. Click on it to copy the Space Token
Each space has a unique token. Make sure you’re using the correct space token for your API requests.

​
How to Get Your Agent Handle

Follow these steps to obtain your Agent Handle from the Unpod Dashboard:
  1. Login to the Unpod Dashboard
  2. On the left sidebar, click on the Studio View
  3. Click on Create AI Identity, you will be redirected to the Agents page
  4. Click on the agent for which you want the Agent Handle
  5. On the right sidebar, you will see three dots behind Publish, click on that
  6. You will see the Copy Handle option
  7. Click on it to copy the Agent Handle
Each agent has a unique handle. Make sure you’re using the correct agent handle for your API requests.

​
Best Practices

  1. Secure Storage: Never expose your API tokens in client-side code or public repositories
  2. HTTPS Only: Always use HTTPS for all API requests
  3. Header Validation: Always include required headers (Org-Handle, Product-ID) where needed
  4. Error Handling: Implement proper error handling for authentication failures
  5. Rotation: Rotate API tokens periodically for enhanced security