Skip to navigation
Tokenization

Check a token

View as Markdown

Check whether a token can still be used, and what it is scoped to.

Worth calling before a batch run, and worth calling when a tokenized execution is refused: this is where the reason lives.

status_code, and what each one means for you

StatusWhat it meansWhat to do
T10N_OKReady. The last run authenticated.Use it.
T10N_KOUsable, but the last run did not complete.Use it; if it keeps failing, have your customer connect the account again — that renews this token.
T10N_LOGIN_LOCKThe source rejected the stored credentials, or locked the account.Do not retry. Have your customer connect the same account again: exchanging that ticket renews this token — same token_id, new key.
T10N_SYSTEM_LOCKTemporarily suspended by the platform.Wait; if it persists, contact support.
T10N_REVOKEDRevoked. It will never run again.Delete it. A new connection gets a new token_id.
T10N_BROKENThe stored material can no longer be used.Have your customer connect the account again: that renews it.

context repeats the scope: engine_reference, customer_id, locking_hash and the features the token may request, and source_execution_id, the execution whose credentials it holds now. date_expiration is the hard end of its life — 90 days from the last exchange, not extended by use — after which the stored credentials are deleted. Renewing the connection before then sets a new one.

The token key is never returned here. If you lost it, the token is unusable until your customer connects the account again, which renews it with a new key.

This endpoint needs to be executed with an app secret, so should always be used in server side without exposing the secret to customers.

Authentication

X-APP-SECRETstring
Application Secret

Path parameters

token_idstringRequiredformat: "object-id"

The stored-credentials token, as the exchange returned it.

Response

200 OK
What the token is for — the engine, the customer and the features it was scoped to — and whether it still works. It never carries the credentials, nor your key: nothing here can be turned back into a password.

token_idstringformat: "object-id"

Identifies the stored credentials — the same id you send when you run an execution with them.

date_createdstringformat: "datetime"
When the first ticket was exchanged for this token. A renewal keeps it.
date_expirationstringformat: "datetime"

When it stops working. Decided at the exchange and not extended by use: a token that runs every month still expires on this date. Connecting the same account again renews the token — the same token_id — and sets a new date.

status_codeenum
Whether the token is usable. Branch on this, not on the dates.
contextobject
Credentials context.
status_descriptionstringOptional

Why it is in that state, in our words. Prose: read it, do not parse it.

status_messagestringOptional
A message written to be shown to a person, when there is one.

Errors

404
Not Found Error
422
Unprocessable Entity Error