View as Markdown Open in ChatGPT Open in Claude

Session Token Endpoint

The REST endpoint your server calls to mint a short-lived session token. Request, response, error codes, and an OpenAPI reference.

This is the single REST endpoint behind the SDK's getSessionToken flow. Call it from your server with your secret API key; return the token to the SDK. For the end-to-end setup and per-stack backend examples, see Authentication.

Endpoint

http

POST https://api.avatarfactory.in/v1/session/token
Authorization: Bearer <YOUR_SECRET_API_KEY>
Content-Type: application/json

{ "avatarId": "default" }

Token flow

text

Browser (SDK)          Your server              AvatarFactory API
     |                       |                          |
     |  getSessionToken()    |                          |
     |---------------------->|                          |
     |                       |  POST /v1/session/token  |
     |                       |  Bearer <secret key>     |
     |                       |------------------------->|
     |                       |     { sessionToken }     |
     |                       |<-------------------------|
     |     sessionToken      |                          |
     |<----------------------|                          |
     |     open connection with sessionToken            |
     |------------------------------------------------->|

The browser never holds your API key and never calls this endpoint directly.

Request

Headers

Header	Required	Value
`Authorization`	Yes	Bearer token using your secret API key (`af_live_*`).
`Content-Type`	Yes	application/json

Body

Field	Type	Required	Description
`avatarId`	`string`	Yes	The avatar to start a session for. Use "default" for the public demo avatar, or one of your published avatar IDs.

Response

200 OK

json

{ "sessionToken": "<short-lived session token>" }

The token is short-lived and single-use — the SDK requests a fresh one on each connect and reconnect.

Error codes

Status	Meaning	Fix
`400`	Bad Request	Missing or malformed avatarId.
`401`	Unauthorized	Missing or invalid API key — check the Authorization header.
`403`	Forbidden	Your plan isn't allowed to use this avatar (e.g. a premium avatar on a free plan).
`429`	Too Many Requests	Rate limit exceeded — retry after a short delay with backoff.

OpenAPI

yaml

openapi: 3.1.0
info:
  title: AvatarFactory API
  version: "1.0.0"
servers:
  - url: https://api.avatarfactory.in/v1
paths:
  /session/token:
    post:
      summary: Mint a short-lived session token
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [avatarId]
              properties:
                avatarId:
                  type: string
                  description: '"default" or a published avatar ID'
      responses:
        "200":
          description: Token minted
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionToken:
                    type: string
        "400": { description: Missing or malformed avatarId }
        "401": { description: Missing or invalid API key }
        "403": { description: Avatar not allowed on this plan }
        "429": { description: Rate limit exceeded }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

Building the backend now? Authentication has copy-paste implementations for cURL, Node/Express, Next.js, and Python.

Changelog

Token flow

text

Browser (SDK)          Your server              AvatarFactory API
     |                       |                          |
     |  getSessionToken()    |                          |
     |---------------------->|                          |
     |                       |  POST /v1/session/token  |
     |                       |  Bearer <secret key>     |
     |                       |------------------------->|
     |                       |     { sessionToken }     |
     |                       |<-------------------------|
     |     sessionToken      |                          |
     |<----------------------|                          |
     |     open connection with sessionToken            |
     |------------------------------------------------->|

The browser never holds your API key and never calls this endpoint directly.

Header

Required

Value

Authorization

Yes

Bearer token using your secret API key (af_live_*).

Content-Type

Yes

application/json

Field

Type

Required

Description

avatarId

string

Yes

The avatar to start a session for. Use "default" for the public demo avatar, or one of your published avatar IDs.

Error codes

Status	Meaning	Fix
`400`	Bad Request	Missing or malformed avatarId.
`401`	Unauthorized	Missing or invalid API key — check the Authorization header.
`403`	Forbidden	Your plan isn't allowed to use this avatar (e.g. a premium avatar on a free plan).
`429`	Too Many Requests	Rate limit exceeded — retry after a short delay with backoff.

OpenAPI

yaml

openapi: 3.1.0
info:
  title: AvatarFactory API
  version: "1.0.0"
servers:
  - url: https://api.avatarfactory.in/v1
paths:
  /session/token:
    post:
      summary: Mint a short-lived session token
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [avatarId]
              properties:
                avatarId:
                  type: string
                  description: '"default" or a published avatar ID'
      responses:
        "200":
          description: Token minted
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionToken:
                    type: string
        "400": { description: Missing or malformed avatarId }
        "401": { description: Missing or invalid API key }
        "403": { description: Avatar not allowed on this plan }
        "429": { description: Rate limit exceeded }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

Building the backend now? Authentication has copy-paste implementations for cURL, Node/Express, Next.js, and Python.