Tokens

Exchange application credentials for a short-lived widget JWT

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.

post/tokens

Request

  • Base URL: https://api.customdomain.ai/v1
  • URL: https://api.customdomain.ai/v1/tokens
  • Auth: none required

Request body

application_idstring required
client_secretstring required
domainstring

Optional. Binds the token to a single hostname.

domainsstring[]

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_refstring

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_emailstring email

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'connect' | 'app'

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.

Response

Token issued

tokenstring required

the widget JWT (Bearer)

token_typestring required
expires_ininteger required

lifetime in seconds (default 900)

scope'connect' | 'app'

the scope the token was minted with

Example response

{
  "token_type": "Bearer"
}

Changes

No recorded changes to this operation across all 1 revision of this API.