Create Token

POST

https://api.orga-ai.com/v1/realtime/client-secrets?email=<encoded_email>

Exchanges your long-lived server API key for a short-lived ephemeral token that clients can use to authenticate with Orga’s real-time APIs (e.g., ICE Config and Calls).

This endpoint must be called only from your backend using your API key. API keys should never appear in client-side applications.

Headers

Name	Required	Description
`Authorization`	✅	Your Orga server API key, in the format: `Bearer sk_orga_ai_...`
`Content-Type`	✅	`application/json`

Request Body

Empty body — this endpoint currently does not accept any JSON fields.

Example Request (cURL)


curl -X POST "https://api.orga-ai.com/v1/realtime/client-secrets?email=test%40example.com" \
  -H "Authorization: Bearer sk_orga_ai_your_server_api_key" \
  -H "Content-Type: application/json"

Example Response


{
  "ephemeral_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI2OGRhNjM3YTIwN2YyMmVmZTE0MjVkMGQiLCJhcGlfa2V5X2lkIjoiNjhkYTY1ZDMyMDdmMjJmMjVkMjkiLCJzY29wZSI6ImFwaSIsImlhdCI6MTc2Mjg2MDg4MywiZXhwIjoxNzYyODYxNzgzfQ.fXdwcLxHg0vKc0gnz9U_NnlIGpOyI81e-s951wDRYvM",
  "token_type": "bearer",
  "expires_at": "2025-11-11T11:49:43.252934"
}

Field	Type	Description
ephemeral_token	string	The short‑lived JWT clients use for authentication
token_type	string	Always “bearer”
expires_at	string (ISO 8601)	Expiration timestamp for the token

Error Responses

401 - Invalid API Key

Returned when the server API key is missing or invalid


{
  "error": {
    "message": {
      "error": {
        "message": "Incorrect or inactive API key provided.",
        "type": "invalid_request_error",
        "param": null,
        "code": null
      }
    },
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

404 - Invalid Email or User Not found

Returned when the required email query parameter does not correspond to a valid user.


{
  error: {
    message: "User not found.",
    type: "not_found_error",
    param: null,
    code: null
  }
}

422 - Missing Encoded Email

Returned when the email query parameter is omitted or not properly encoded.


{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "email"],
      "msg": "Field required",
      "input": null
    },
    {
      "type": "missing",
      "loc": ["query", "another_required_field"],
      "msg": "Field required",
      "input": null
    }
  ]
}

Usage Notes

Call this endpoint only from your secure server.
The returned ephemeral_token can be used as Authorization: Bearer for:
- GET /v1/realtime/ice-config
- POST /v1/realtime/calls
Tokens expire quickly — request a new one per session.
The email query parameter is temporary and will be deprecated in a future API version.

💡 Tip: Always Base64 or URI‑encode the email address when constructing this URL.