CustomDomain Tokens API
Minting short-lived widget JWTs for the browser.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/customdomain-ai:customdomain-ai-tokens-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Customdomain Ai Tokens API
version: '1.0'
license:
name: Apache-2.0
identifier: Apache-2.0
description: 'Operations tagged Tokens across 2 of this provider''s published API definitions: customdomain-ai-openapi-original.json, customdomain-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.customdomain.ai/v1
description: Hosted control-plane
- url: http://localhost:8080/v1
description: Local control-plane
security:
- apiKey: []
tags:
- name: Tokens
description: Minting short-lived widget JWTs for the browser.
paths:
/tokens:
post:
operationId: createWidgetToken
summary: Exchange application credentials for a short-lived widget JWT
tags:
- Tokens
description: Server-side only. Trade an application's `client_secret` for a short-lived widget JWT the browser can use on the Connect endpoints. Never ship the `client_secret` or an API key to the browser.
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- application_id
- client_secret
properties:
application_id:
type: string
client_secret:
type: string
domain:
type: string
description: Optional. Binds the token to a single hostname.
domains:
type: array
items:
type: string
description: Optional. A list of hostnames the token may act on, so a multi-domain flow needs one token instead of one per domain. Each entry is normalized and duplicates and blanks are dropped. Additive to `domain`; omit both for a token that is not bound to a hostname.
end_user_ref:
type: string
maxLength: 256
description: 'Optional. Binds the token to one end user: your own id for them. A connection created with the token is stamped with it (a different `end_user_ref` in the create body is refused), and an end user''s token removes a domain, or reads its monitoring, services and timeline, only when it is bound to the domain and minted with the connection''s own `end_user_ref`.'
end_user_email:
type: string
format: email
maxLength: 254
description: 'Optional. The email address of the end user this token is for. It is never put in the token: it is kept on our side and a connection created with this token takes it, so that after a Move the person gets the new DNS records by email on your behalf. An `end_user_email` on the connection create wins over it.'
scope:
type: string
enum:
- connect
- app
default: connect
description: '`connect` (the default) is an END USER''s token for the widget: it runs the connect flow for a domain (check, create, read its own connection, verify, one-click and OAuth starts, sharing, telemetry, diagnose) and nothing else, because it lives in that end user''s browser. `app` lets your server act as the whole application (list every connection, manage webhooks, configure SSL and Power, bulk create, purchases). Never hand an `app` token to a browser.'
responses:
'201':
description: Token issued
content:
application/json:
schema:
type: object
required:
- token
- token_type
- expires_in
properties:
token:
type: string
description: the widget JWT (Bearer)
token_type:
type: string
examples:
- Bearer
expires_in:
type: integer
description: lifetime in seconds (default 900)
scope:
type: string
enum:
- connect
- app
description: the scope the token was minted with
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'429':
description: '`rate_limited`: too many token requests from this address, or too many failed ones (unknown application or wrong secret) for this `application_id`. A request with the right secret is limited only by its address. Retry shortly.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://api.customdomain.ai/v1
description: Hosted control-plane
- url: http://localhost:8080/v1
description: Local control-plane
components:
responses:
Error:
description: 'Error envelope: {code, title, details}.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
required:
- code
- title
properties:
code:
type: string
description: stable machine code, e.g. invalid_request, unauthorized, not_found, service_unavailable, internal_error
title:
type: string
description: human-readable summary
details:
type: string
description: optional extra context
securitySchemes:
managementKey:
type: http
scheme: bearer
description: Operator management key. Gates provisioning + reads across tenants.
provisionSecret:
type: apiKey
in: header
name: X-Provision-Secret
description: Narrow secret held by the customer console's server, for signup provisioning and its other server to server calls (also accepted as a Bearer token, except on POST /audit, where a Bearer is always a tenant credential).
apiKey:
type: http
scheme: bearer
description: Long-lived tenant API key, cd_live_… (production) or cd_test_… (staging, development), stored hashed. Keys created before the switch to cd_ start with sk_live_… / sk_test_… and are still accepted. Scoped to the owning application's tenant.
widgetJWT:
type: http
scheme: bearer
bearerFormat: JWT
description: Short-lived widget JWT minted server-side via POST /v1/tokens. Scoped to one application (and optionally one domain).
browserSession:
type: http
scheme: bearer
description: The session token of one cloud browser sign in, returned by `POST /browser-sessions:redeem`. It binds one session, one connection and one workspace, lives at most as long as the session, and stops working the moment the session ends. It lives in the popup's memory only.
agentToken:
type: oauth2
description: 'A delegated agent access token: an ES256 JWT that lives 15 minutes, sent as a bearer token. A person approves an agent in the console and the agent exchanges its authorization code (with PKCE) at the token endpoint. The token carries the workspace, the one application the grant is bound to, the grant, the approved scopes and its audience, and is verified against `/.well-known/jwks.json`. A route that accepts it lists the scope it needs; a token without the scope is refused with `403`, and a connection or order of another application answers `404`.'
flows:
authorizationCode:
authorizationUrl: https://api.customdomain.ai/oauth/agent/authorize
tokenUrl: https://api.customdomain.ai/oauth/agent/token
refreshUrl: https://api.customdomain.ai/oauth/agent/token
scopes:
domains:read: Look at availability, connections, records, certificates, diagnoses, orders and the billing standing.
domains:connect: Connect a domain, recheck it, reapply its records and start a one click setup.
domains:disconnect: Remove a connected domain. The call must name the domain.
domains:purchase: Buy a domain, up to the grant's monthly spend cap.
x-refined-from:
- customdomain-ai-openapi-original.json
- customdomain-ai-openapi.yml