Create link token

---

Link tokens allow your customers to connect their apps with Truto. Link tokens are used to initiate a connection flow handled by Truto and the end of this connection flow, an Integrated Account is created. This integrated account acts as a link between your Truto account and the app your customer has connected. To create a link token, you need to specify a tenant_id in the request body which acts as a lookup key for an integrated account. In most cases, you can just use your customer's primary key or unique ID as the tenant_id.

TIP

Tenant IDs do NOT need to be unique. For example, one of your customers could connect multiple apps to your Truto account. You could still use the customer's primary key as tenant_id for all the apps that they connect and look them all up using the customer's primary key.

Reauthorizing an integrated account

An integrated account can be reauthorized by creating a link token for it. Instead of tenant_id, you need to specify the id of the integrated account you need to reauthorize as the integrated_account_id attribute in the request body. Do NOT specify tenant_id. You can use it similar to other link tokens, with the only difference being that the customer will automatically land on the specific integration's page in Truto's connection UI and will be asked to proceed with connecting the application. After the connection flow completes, the new credentials will be updated in the integrated account.

Custom OAuth Scopes

You can specify custom OAuth scopes using the scopes field for both new integrated accounts and when reauthorizing existing ones. These scopes will take precedence over any unified model scopes or integration default scopes during the OAuth flow. This is useful when you need to request additional permissions or restrict the scope of access for a specific integration.

Static Gate

You can specify a static gate for an integrated account by providing the truto_static_gate_id field. When set, all outbound API requests made by this integrated account will be routed through the static gate's domain instead of directly to the Truto's API. This is useful for scenarios where you need to proxy requests through a specific domain or gateway. The static gate must be accessible to the user's environment.

Endpoint

POST /link-token

Request Body

tenant_id

string

The ID of the tenant you want to create a link token for. Required if you are creating a link token for a new integrated account.

Example: acme-1

integrated_account_id

string · uuid

The ID of the integrated account you want to reauthorize. Do NOT specify tenant_id if you are reauthorizing an integrated account.

Example: 1ba1f401-7183-47c5-9e39-e8e257e3c795

context

object

The context of the integrated account. You can find these in the Variables section of an integrated account in the Truto UI.

Example: { "label": "Production Hubspot Account" }

redirect_uri

string

The URI where the user should be redirected after the connection flow is complete. This is especially useful when you are authenticating via a Desktop app.

Example: https://example.com/redirect

scopes

string[]

OAuth scopes to request during authentication. These scopes will take precedence over unified model scopes and integration default scopes.

Example: [ "read:users", "write:contacts" ]

persist_previous_context

boolean

If set to true, the context of the integrated account will be persisted when reconnecting. Set to false by default.

truto_static_gate_id

string · uuid

The ID of the static gate to associate with this integrated account. The static gate must be accessible to the user's environment.

Example: 1ba1f401-7183-47c5-9e39-e8e257e3c795

Response Body

link_token

string

The link token that can be used to initiate a connection flow.

Example: efe6413c-941a-4ca6-8f22-defbf758b824