Stored credentials | INFONITE

Tokenization replaces a stored password with a token: an identifier and a key that mean “run that access, through this application, for that customer, for these features” — and nothing else, anywhere else. You keep the key half; the platform keeps the credentials, encrypted under something only your key can derive.

How tokenization works

Read this first if you have not. The key derivation, why neither side can open the credentials alone, what happens if you lose your key, and what shared responsibility means here in the exact sense of the term. This page is the API; that one is the design.

Tokenization is enabled per application. If yours does not have it, the token endpoints answer 403, and asking for tokenized_access when you start an execution is refused with 400 and T10N_FORBIDDEN — no ticket is ever issued, and no execution is created. Talk to support to have it turned on.

How you get a token

Ask for a ticket when you start an execution

Send base_configurations.tokenized_access: true to Start an Execution. The 202 comes back with a ticket — a single-use, short-lived string that exists only to be exchanged.

Exchange it, once

Exchange a Ticket takes the execution_id and the ticket, and returns the real thing: a token_id and a token_key, plus the context the token is locked to.

Use it instead of credentials

Start a Tokenized Execution takes token where the other endpoint takes parameters. Everything else about the execution behaves identically.

What the exchange returns

{
  "token": {
    "token_id": "6aa3d8b418d1c5dc9a8e3d36",
    "token_key": "a3f1…"
  },
  "context": {
    "engine_reference": "DEMOBANKXXXXFIN100ES9999-mobile",
    "customer_id": "my-customer-1",
    "locking_hash": "v1.36GHPwfDK-UUZGG4fb1jtg",
    "features": ["customer_information_read", "accounts_read", "cards_read"]
  }
}

Store both halves, and treat token_key like a password. It is the only copy — no screen, no endpoint and no support agent will read it back to you, because nothing on our side holds it. Lose it and the stored credentials can never be opened again, by anyone: revoke the token and mint a new one from a fresh run with the real credentials. Why that is, and why it is deliberate.

What a token is allowed to do

The scope is fixed at the moment the token is created, and it cannot be widened afterwards.

Locked to	Meaning
One application	Yours. A token is meaningless without your application secret alongside it.
One engine	The one that produced it.
One customer	The `customer_id` of the original execution. Sending a different one changes nothing.
A set of features	You may request fewer on a given run. Requesting one that was not in the original scope is refused.

Need a wider scope? Run a parametrized execution with the features you want and mint a new token from it. That is deliberate: broadening what stored credentials may reach should require the credentials again.

Validity is 90 days from the exchange, and using the token does not extend it. The expiry is decided when the token is minted; when it arrives, the stored credentials are deleted and the token stops existing.

Put the renewal in your calendar, not in your incident log. A quarterly re-run that never re-mints its tokens works perfectly for three months and then fails for everybody at once. Read date_expiration from Token Status, and mint a fresh token — from a new parametrized execution, with the credentials — before it lapses.

Reading a token’s health

Token Status is the endpoint to call before a batch, and the one that explains a refusal.

Status	What it means	What to do
`T10N_OK`	Ready — the last run authenticated.	Use it.
`T10N_KO`	Usable, but the last run did not complete.	Use it; if it keeps failing, ask for the credentials again.
`T10N_LOGIN_LOCK`	The source rejected the stored credentials, or locked the account.	Do not retry. Ask your customer for their access again and mint a new token.
`T10N_SYSTEM_LOCK`	Temporarily suspended by the platform.	Wait; if it persists, contact support.
`T10N_REVOKED`	Revoked. It will never run again.	Delete it and mint a new one.
`T10N_BROKEN`	The stored material can no longer be used.	Mint a new one.

A tokenized execution against a locked token answers 423 rather than starting, so a batch fails fast instead of hammering an institution with credentials it has already rejected.

A locked token means a person has to act — retrying makes it worse. Institutions count failed logins, and enough of them locks the account for your customer, not just for you.

Revoking

Delete a Token revokes it immediately and marks the stored credentials for deletion. Call it when a customer withdraws consent, closes their account with you, or asks you to stop — and after any suspicion that your half leaked.

Revoking does not touch executions already run with that token, nor the records they produced: those are removed with Delete an Execution.

Your customer’s right to be forgotten is two calls, not a support ticket. Revoke the token, delete the executions. Both are immediate and neither needs us.

`locking_hash`, and recognising a returning login

Every execution that gets as far as authenticating publishes a locking_hash: a stable fingerprint of the fixed part of the credentials — the username, typically, or whatever the engine’s locking_fields declare. The same access always produces the same value, and the value reveals nothing.

It lets you answer “do we already have a token for this login?” without storing what the login is, and it is what makes a per-customer credential store possible with no credentials in it.