Skip to main content
This page covers the backend flow for exchanging and using Link tokens. For the Link frontend, see the Link Web SDK.

Authentication

A Server app signs /v1/link/token and /v1/link/revoke with HTTP Basic: its client_id as the username and its client_secret as the password. A Browser Or Native app has no secret, and sends client_id as a field instead. /v1/link/grant, /v1/link/usage, and model requests take an access token: Authorization: Bearer dlk_at_…. Request bodies are form-encoded or JSON. In the samples, the refresh token is the one you saved for the user, and the access token is the one Refresh returns.

Exchange Code

POST /v1/link/token The /v1/link/token endpoint exchanges the code from Link for a refresh_token, which identifies the new connection. Store the refresh_token: every later call takes it. A code is single-use and expires 10 minutes after Link provides it.

Request Fields

string
required
authorization_code
string
required
The code from DariLink.open.
string
required
The PKCE verifier for the code: the codeVerifier from DariLink.open, or the one your server kept.
string
required
The redirect URI Link was opened with.
string
Your app’s client_id. Required for an app without a secret; a Server app sends it with HTTP Basic.

Response Fields

string
The token for the connection. For a Server app it never changes, and works only with your client_secret. For an app without a secret it is replaced on every refresh.
string
A token for model requests and for /v1/link/grant and /v1/link/usage.
integer
The seconds until access_token expires: 3600.
string
Bearer
string
The identifier of the connection. Pass it to Link to open update mode.
The response also carries every field of Get Grant, such as plans and models.
Response Object

Refresh

POST /v1/link/token Gets a new access token for a connection. Access tokens last an hour, and earlier ones keep working until they expire, so any number of processes can refresh at once.

Request Fields

string
required
refresh_token
string
required
The connection’s refresh_token.
string
Your app’s client_id. Required for an app without a secret.

Response Fields

The same as Exchange Code. For a Server app, refresh_token is the one you sent. For an app without a secret it is new, and the one you sent stops working: save it before using the access token.

Create Child Token

POST /v1/link/token Trades an access token for a child token that serves only the models it names, for a sandbox or worker that must hold nothing more. A child token cannot refresh, mint another token, or read the grant or its usage, and it stops working when the connection does. See Sandboxes And Workers.

Request Fields

string
required
urn:ietf:params:oauth:grant-type:token-exchange
string
required
An access token of the connection.
string
required
urn:ietf:params:oauth:token-type:access_token
string
required
A model the child token serves, such as gpt-5.5. Repeat the field for up to 16 models. A model the connection cannot serve refuses the whole request with invalid_target.
string
The thinking level the models are served at, such as high. Give it once for every model, or once per model in the same order, with default to leave one unpinned.
integer
The seconds the child token lasts.Minimum: 60Maximum: 43200Default: 3600
string
Labels for the child token’s requests, as comma-separated key=value pairs. Get Usage filters and groups by them.

Response Fields

string
The child token. It is an API key for the gateway’s model endpoints.
integer
The seconds until it expires.
[object]
The models it serves.
object
The tags on its requests. Absent when none were given.
string
The connection it belongs to.
Response Object

Get Grant

GET /v1/link/grant Gets what a connection holds now: its plans and API keys, whether each can serve, the models they serve, and your user’s budget. It makes no provider call, so it is the cheap check before a long run.

Request Fields

This endpoint takes no request fields. It takes the access token as a Bearer token.

Response Fields

string
The identifier of the connection.
string
Whether the connection can serve your app now.ready: It can.budget_limit: Your app has used the budget your user set, until available_at.
nullable, string
When a budget_limit connection serves again.Format: date-time
[object]
The caps your user set on what your app may use, across all the connection’s plans and keys. Empty for no cap. See Budgets.
[object]
The plans and API keys your user shared.
[object]
The models your app can name now, each with the id a request uses and its display name.
boolean
Whether dari/routing serves your app now.
string
Dari’s page for this connection, where your user sees its usage, sets its budget, and disconnects.
string
Your app’s name, as Link shows it.
string
Your app’s client_id.
string
When your user connected.Format: date-time
Response Object

Get Usage

GET /v1/link/usage Gets what a connection’s requests used, child tokens’ included. Every request is recorded once it finishes, a moment after the response. See Usage And Budgets. One request’s usage is at GET /v1/link/usage/requests/<X-Request-Id>, in the same shape.

Request Fields

string
Only requests carrying this tag, as key=value. Repeat the field to require several. Requests are tagged with the X-Dari-Tags header or by a child token’s tags.
string
Only requests received at or after this time.Format: date-time
string
Only requests received before this time.Format: date-time
string
tag:<key> also totals the usage per value of that tag, in by_tag.

Response Fields

integer
The number of requests.
integer
The requests the provider or Dari failed. They count in requests too.
integer
Input tokens, excluding cache reads and writes, whatever protocol the requests spoke.
integer
Output tokens.
integer
Tokens read from the prompt cache.
integer
Tokens written to the prompt cache.
[object]
The same totals per model and thinking level served, most requests first.
[object]
With group_by: the same totals per value of that tag. value is null for requests without it.
nullable, string
Every request received before this time is counted. null when the gateway cannot tell.
Response Object

Revoke

POST /v1/link/revoke Ends a connection, as when your user disconnects in your app. Every token of the connection stops working at once.

Request Fields

string
required
Any token of the connection. Use the refresh_token.
string
Your app’s client_id. Required for an app without a secret.

Response Fields

This endpoint answers 200 with an empty body, whether or not the token was live.

Register App

POST /v1/link/register Registers an app and returns its client_id. On hosted Dari, register in the console instead, or send this request with an organization’s API key. A self-hosted gateway may allow it without a key. Registering gives your app no access by itself. Every user still allows it in Link.

Request Fields

string
required
The name of your app, as Link shows it.
[string]
required
The redirect URIs Link may return to. Each is https, or http on localhost or 127.0.0.1 for development. A self-hosted gateway can allow http on private dev hosts. See Run A Gateway.Min items: 1
string
client_secret_basic registers a Server app, which gets a client_secret. Leave it out for a Browser Or Native app, which has none.Use a Server app whenever you have a backend: its refresh token never rotates, so it is one string to store and any number of your servers can share it.
cURL

Response Fields

string
Your app’s public identifier.
string
Your server’s private key. Returned only for a Server app, and only this once. Store it like a password.
Response Object

Authorize

GET /v1/link/authorize The Link page itself. DariLink.open builds this URL and opens it in a popup. An app that cannot use the Web SDK, such as a CLI, opens it in the browser itself and receives the code on its redirect URI.

Request Fields

string
required
code
string
required
Your app’s client_id.
string
required
One of your app’s registered redirect URIs, exactly as registered.
string
required
A random value your app makes. Link returns it with the code: check that it matches.
string
required
The PKCE challenge: the base64url SHA-256 of the verifier your app keeps.
string
required
S256
string
web_message posts the result to the window that opened the page, as {"type": "dari-link", "code", "state"} or with error. By default the result is sent on a redirect to redirect_uri.
string
The kinds of plan to offer, separated by spaces. See plans.
string
The providers whose API keys your app can use, separated by spaces.
string
The coding agents your app runs itself, separated by spaces. See clients.
string
An existing connection, to open in update mode.
Authorize URL

Token Prefixes