Skip to content

Knowledgebase

Exchange a one-time connector bootstrap token safely

domain-nexus, development

A connector bootstrap token is a one-time setup credential exchanged for the integration's usable credentials. It is not a recurring API password and is not the email/API-key value used by a connector that explicitly asks for those fields. Use this workflow only when the supplied connector or authorised setup process issues a bootstrap token.

01 Make the exchange

Method Resource Scope Idempotency-Key
POST /v2/auth/token none Not required by this route

Append the route to the current API base given in the getting-started guide. Send a JSON object containing the issued token and a stable identifier for this connector installation:

Structured data example
{
  "bootstrap_token": "ONE_TIME_TOKEN_FROM_SETUP",
  "installation_id": "billing-installation-a"
}
  1. Create the installation identifier once and keep it with the connector configuration. Do not generate a new identity for every request.
  2. Submit the exchange over HTTPS. This route authenticates the token in the body, so it does not require ordinary API authentication headers or a kernel idempotency key.
  3. Store the returned credential material immediately in the connector's supported secret storage. Avoid logging the response body.
  4. Perform a small authenticated read with the issued credential, then remove the bootstrap token from any temporary setup notes or unsecured location.

What if the response is lost?

The token is single-use. Do not assume it can be replayed indefinitely to reveal the same secret, and do not keep generating different installation identifiers to force another exchange. Inspect the authorised setup state and obtain a replacement setup credential through the account's supported workflow if needed.

Can I send my account login password here?

No. This endpoint exchanges a specific bootstrap token; it is not a general account-login API. A rejected token needs investigation of its origin, expiry, use and installation context.

When the installed connector instead asks for an API username/email and API key, follow that connector's setup guide. When it asks for an HMAC key ID and secret, keep those fields paired. Distinguishing these credential types avoids a successful setup exchange followed by repeated authentication failures in scheduled jobs.

Was this answer helpful?

Need a little more help?

Our support team can help you find the next step.

Contact support