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
The
code from DariLink.open.The PKCE verifier for the code: the
codeVerifier from DariLink.open, or the one your server kept.Your app’s
client_id. Required for an app without a secret; a Server app sends it with HTTP Basic.Response Fields
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.The identifier of the connection. Pass it to Link to open update mode.
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
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
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.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.Labels for the child token’s requests, as comma-separated
key=value pairs. Get Usage filters and groups by them.Response Fields
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
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.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.
Dari’s page for this connection, where your user sees its usage, sets its budget, and disconnects.
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
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.Response Fields
With
group_by: the same totals per value of that tag. value is null for requests without it.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
Response Fields
This endpoint answers200 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
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: 1client_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
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
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.The kinds of plan to offer, separated by spaces. See
plans.The coding agents your app runs itself, separated by spaces. See
clients.An existing connection, to open in update mode.
Authorize URL