Create client token

POST

/v1/client-tokens

POST

/v1/client-tokens

$ curl -X POST https://api.runtype.com/v1/client-tokens \
>      -H "Authorization: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "allowedOrigins": [
>     "https://example.com",
>     "http://localhost:3000"
>   ],
>   "name": "My Chat Widget",
>   "config": {
>     "placeholder": "Type your message...",
>     "theme": {
>       "mode": "light",
>       "primaryColor": "#007bff"
>     },
>     "welcomeMessage": "Hello! How can I help you today?"
>   },
>   "defaultFlowId": "flow_01jv0000000000000000000001",
>   "environment": "live",
>   "flowIds": [
>     "flow_01jv0000000000000000000001"
>   ],
>   "maxMessagesPerSession": 100,
>   "rateLimitPerHour": 100,
>   "rateLimitPerMinute": 10,
>   "sessionIdleTimeoutMinutes": 30
> }'

1 {
2   "clientToken": {
3     "agentIds": [
4       "string"
5     ],
6     "allowedOrigins": [
7       "string"
8     ],
9     "config": {},
10     "createdAt": "string",
11     "defaultFlowId": "string",
12     "environment": "test",
13     "flowIds": [
14       "string"
15     ],
16     "id": "string",
17     "isActive": true,
18     "lastUsedAt": "string",
19     "maxMessagesPerSession": 1,
20     "name": "string",
21     "pinToVersion": "string",
22     "rateLimitPerHour": 1,
23     "rateLimitPerMinute": 1,
24     "sessionIdleTimeoutMinutes": 1,
25     "targetAlias": "string",
26     "targetVersionId": "string",
27     "tokenHint": "string",
28     "tokenPrefix": "string",
29     "tokenValue": "string",
30     "updatedAt": "string",
31     "conversationCount": 1,
32     "productSurfaceId": "string"
33   },
34   "token": "string",
35   "warnings": [
36     {
37       "message": "string",
38       "type": "string"
39     }
40   ]
41 }

Create a new client token for browser-to-API communication. Returns the plain token value once.

Authentication

AuthorizationBearer

API key or Clerk session token

Request

This endpoint expects an object.

allowedOriginslist of stringsRequired

Allowed request origins for this token. Each entry is an exact origin (https://app.example.com), a wildcard subdomain (https://.example.com), '' for all origins, or the literal ‘native’ — a sentinel that admits requests carrying NO Origin header (native mobile apps). A token with ‘native’ has effectively no origin protection and relies on its capability scope.

Allowed request origins for this token. Each entry is an exact origin (https://app.example.com), a wildcard subdomain (https://*.example.com), '*' for all origins, or the literal 'native' — a sentinel that admits requests carrying NO Origin header (native mobile apps). A token with 'native' has effectively no origin protection and relies on its capability scope.

namestringRequired1-255 characters

agentIdslist of stringsOptionalDefaults to []

configmap from strings to anyOptionalDefaults to {}

defaultFlowIdstringOptional

environmentenumOptionalDefaults to live

Allowed values:

flowIdslist of stringsOptionalDefaults to []

maxMessagesPerSessiondoubleOptional1-1000Defaults to 100

pinToVersionstringOptionalDefaults to latest

Legacy widget-version mode: ‘latest’ or ‘published’. It has never selected an agent version and still does not. An agent version id (agentver_…) is rejected on create; use targetVersionId to pin a version or targetAlias to follow a release alias. An update may echo back the value already stored.

productSurfaceIdstringOptional

rateLimitPerHourdoubleOptional1-10000Defaults to 100

rateLimitPerMinutedoubleOptional1-1000Defaults to 10

sessionIdleTimeoutMinutesdoubleOptional1-1440Defaults to 30

targetAliasstring or nullOptional

Release alias this token follows. Re-resolved on every admission, so a deploy at that alias changes what the token runs. Mutually exclusive with targetVersionId.

targetVersionIdstring or nullOptional

Exact agent version this token runs. Never re-resolved. Mutually exclusive with targetAlias, and the token must carry exactly one agent id.

Response

Created client token

clientTokenobject

tokenstring

warningslist of objects

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error