> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dari.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Link Endpoints

> API reference for Link tokens, grants, and usage.

This page covers the backend flow for exchanging and using Link tokens. For the Link frontend, see the [Link Web SDK](https://docs.dari.dev/link/web.md).

| Endpoints | |
| - | - |
| [`/v1/link/token`](#exchange-code) | Exchange a code for a refresh token |
| [`/v1/link/token`](#refresh) | Get an access token from a refresh token |
| [`/v1/link/token`](#create-child-token) | Create a child token for a sandbox or worker |
| [`/v1/link/grant`](#get-grant) | Get what a connection holds and whether it can serve |
| [`/v1/link/usage`](#get-usage) | Get what a connection's requests used |
| [`/v1/link/revoke`](#revoke) | Disconnect |
| [`/v1/link/register`](#register-app) | Register an app |
| [`/v1/link/authorize`](#authorize) | The Link page itself |

| See also | |
| - | - |
| [Errors](https://docs.dari.dev/link/reference/errors.md) | Every error code, and what to do about it |
| `/.well-known/oauth-authorization-server` | The gateway's OAuth 2.0 metadata |

## 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](#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

**grant\_type** `string` *required*

`authorization_code`

**code** `string` *required*

The `code` from [`DariLink.open`](https://docs.dari.dev/link/web#open).

**code\_verifier** `string` *required*

The PKCE verifier for the code: the `codeVerifier` from `DariLink.open`, or the one your server kept.

**redirect\_uri** `string` *required*

The redirect URI Link was opened with.

**client\_id** `string`

Your app's `client_id`. Required for an app without a secret; a Server app sends it with HTTP Basic.

```ts Node theme={null}
import { exchange } from "@mupt-ai/dari-gateway/link/client";

// 1. Redeem the code your page got from DariLink.open.
const tokens = await exchange({
  gatewayUrl: DARI_GATEWAY_URL,
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
  redirectUri: "https://myapp.com/dari/callback",
  code,
  codeVerifier,
});

// 2. Save tokens.refreshToken to your database, with your user.
```

```python Python theme={null}
import requests

# 1. Redeem the code your page got from DariLink.open.
reply = requests.post(f"{DARI_GATEWAY_URL}/v1/link/token",
    auth=(CLIENT_ID, CLIENT_SECRET),
    data={
        "grant_type": "authorization_code",
        "code": code,
        "code_verifier": code_verifier,
        "redirect_uri": "https://myapp.com/dari/callback",
    })
reply.raise_for_status()
tokens = reply.json()

# 2. Save tokens["refresh_token"] to your database, with your user.
```

```go Go theme={null}
// 1. Redeem the code your page got from DariLink.open.
form := url.Values{
	"grant_type":    {"authorization_code"},
	"code":          {code},
	"code_verifier": {codeVerifier},
	"redirect_uri":  {"https://myapp.com/dari/callback"},
}
req, _ := http.NewRequest("POST", dariGatewayURL+"/v1/link/token",
	strings.NewReader(form.Encode()))
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
req.SetBasicAuth(clientID, clientSecret)
res, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
defer res.Body.Close()
var tokens struct {
	RefreshToken string `json:"refresh_token"`
	GrantID      string `json:"grant_id"`
}
json.NewDecoder(res.Body).Decode(&tokens)

// 2. Save tokens.RefreshToken to your database, with your user.
```

```bash cURL theme={null}
curl -X POST $DARI_GATEWAY_URL/v1/link/token -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code -d code=$CODE -d code_verifier=$CODE_VERIFIER \
  -d redirect_uri=https://myapp.com/dari/callback
```

#### Response Fields

**refresh\_token** `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.

**access\_token** `string`

A token for model requests and for `/v1/link/grant` and `/v1/link/usage`.

**expires\_in** `integer`

The seconds until `access_token` expires: 3600.

**token\_type** `string`

`Bearer`

**grant\_id** `string`

The identifier of the connection. Pass it to Link to open [update mode](https://docs.dari.dev/link/manage-connections.md#update-mode).

The response also carries every field of [Get Grant](#get-grant), such as `plans` and `models`.

```json Response Object theme={null}
{
  "access_token": "dlk_at_wjx5Uhe6XgyXdtFXrBIrcFMS_kMhAQUAI6IapLEgvFE",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dlk_rt_L3-h1iAR1Y-xYZfgkKCeHRr1ACYbEKDUjWutW7t68mI",
  "grant_id": "lgr_0deb6bbf7672493ba67ef0a9edfb0e8c",
  "state": "ready",
  "plans": [...],
  "models": [...]
}
```

***

## 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

**grant\_type** `string` *required*

`refresh_token`

**refresh\_token** `string` *required*

The connection's `refresh_token`.

**client\_id** `string`

Your app's `client_id`. Required for an app without a secret.

```ts Node theme={null}
import { refresh } from "@mupt-ai/dari-gateway/link/client";

const { accessToken, expiresAt } = await refresh({
  gatewayUrl: DARI_GATEWAY_URL,
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
  refreshToken,
});

// Or let the client do it: linkFetch, grant, usage, and childToken take the
// refreshToken and keep an access token for you.
```

```python Python theme={null}
import requests

reply = requests.post(f"{DARI_GATEWAY_URL}/v1/link/token",
    auth=(CLIENT_ID, CLIENT_SECRET),
    data={"grant_type": "refresh_token", "refresh_token": refresh_token})
reply.raise_for_status()
access_token = reply.json()["access_token"]  # lasts an hour: reuse it
```

```go Go theme={null}
form := url.Values{
	"grant_type":    {"refresh_token"},
	"refresh_token": {refreshToken},
}
req, _ := http.NewRequest("POST", dariGatewayURL+"/v1/link/token",
	strings.NewReader(form.Encode()))
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
req.SetBasicAuth(clientID, clientSecret)
res, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
defer res.Body.Close()
var tokens struct {
	AccessToken string `json:"access_token"`
	ExpiresIn   int    `json:"expires_in"`
}
json.NewDecoder(res.Body).Decode(&tokens)
// tokens.AccessToken lasts tokens.ExpiresIn seconds, an hour: reuse it
```

```bash cURL theme={null}
curl -X POST $DARI_GATEWAY_URL/v1/link/token -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token -d refresh_token=$REFRESH_TOKEN
```

#### Response Fields

The same as [Exchange Code](#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](https://docs.dari.dev/link/sandboxes.md).

#### Request Fields

**grant\_type** `string` *required*

`urn:ietf:params:oauth:grant-type:token-exchange`

**subject\_token** `string` *required*

An access token of the connection.

**subject\_token\_type** `string` *required*

`urn:ietf:params:oauth:token-type:access_token`

**model** `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`.

**thinking** `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.

**expires\_in** `integer`

The seconds the child token lasts.

Minimum: `60`

Maximum: `43200`

Default: `3600`

**tags** `string`

Labels for the child token's requests, as comma-separated `key=value` pairs. [Get Usage](#get-usage) filters and groups by them.

```ts Node theme={null}
import { childToken } from "@mupt-ai/dari-gateway/link/client";

const sandbox = await childToken({
  gatewayUrl: DARI_GATEWAY_URL,
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
  refreshToken,
  models: [{ model: "gpt-5.5", thinking: "high" }],
  expiresIn: 6 * 3600,          // up to 12 hours
  tags: { run: "r1", trial: "7" },
});

// pass sandbox.accessToken (dlk_ct_…) into the sandbox
```

```python Python theme={null}
import requests

sandbox = requests.post(f"{DARI_GATEWAY_URL}/v1/link/token",
    auth=(CLIENT_ID, CLIENT_SECRET),
    data={
        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
        "subject_token": access_token,
        "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
        "model": "gpt-5.5",
        "thinking": "high",
        "expires_in": 6 * 3600,  # up to 12 hours
        "tags": "run=r1,trial=7",
    }).json()

# pass sandbox["access_token"] (dlk_ct_…) into the sandbox
```

```go Go theme={null}
form := url.Values{
	"grant_type":         {"urn:ietf:params:oauth:grant-type:token-exchange"},
	"subject_token":      {accessToken},
	"subject_token_type": {"urn:ietf:params:oauth:token-type:access_token"},
	"model":              {"gpt-5.5"},
	"thinking":           {"high"},
	"expires_in":         {"21600"}, // seconds, up to 12 hours
	"tags":               {"run=r1,trial=7"},
}
req, _ := http.NewRequest("POST", dariGatewayURL+"/v1/link/token",
	strings.NewReader(form.Encode()))
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
req.SetBasicAuth(clientID, clientSecret)
res, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
defer res.Body.Close()
var sandbox struct {
	AccessToken string `json:"access_token"`
}
json.NewDecoder(res.Body).Decode(&sandbox)

// pass sandbox.AccessToken (dlk_ct_…) into the sandbox
```

```bash cURL theme={null}
curl -X POST $DARI_GATEWAY_URL/v1/link/token -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token=$ACCESS_TOKEN \
  -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d model=gpt-5.5 -d thinking=high -d expires_in=21600 -d tags=run=r1,trial=7
```

#### Response Fields

**access\_token** `string`

The child token. It is an API key for the gateway's model endpoints.

**expires\_in** `integer`

The seconds until it expires.

**models** `[object]`

The models it serves.

**properties**

**model** `string`

The model, by its full name.

**thinking** `nullable, string`

The thinking level it is pinned to. `null` when not pinned.

**tags** `object`

The tags on its requests. Absent when none were given.

**grant\_id** `string`

The connection it belongs to.

```json Response Object theme={null}
{
  "access_token": "dlk_ct_LApr1oDxeqxtPhgqHsxPxem5tGiuYP8SZKT1lTuG-9Q",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 21600,
  "grant_id": "lgr_0deb6bbf7672493ba67ef0a9edfb0e8c",
  "models": [{ "model": "dari/model/openai/gpt-5.5", "thinking": "high" }],
  "tags": { "run": "r1", "trial": "7" }
}
```

***

## 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.

```ts Node theme={null}
import { grant } from "@mupt-ai/dari-gateway/link/client";

const connection = await grant({
  gatewayUrl: DARI_GATEWAY_URL,
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
  refreshToken,
});
```

```python Python theme={null}
import requests

connection = requests.get(f"{DARI_GATEWAY_URL}/v1/link/grant",
    headers={"Authorization": f"Bearer {access_token}"}).json()
```

```go Go theme={null}
req, _ := http.NewRequest("GET", dariGatewayURL+"/v1/link/grant", nil)
req.Header.Set("Authorization", "Bearer "+accessToken)
connection, err := http.DefaultClient.Do(req) // the body is the grant
```

```bash cURL theme={null}
curl $DARI_GATEWAY_URL/v1/link/grant -H "Authorization: Bearer $ACCESS_TOKEN"
```

#### Response Fields

**grant\_id** `string`

The identifier of the connection.

**state** `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`.

**available\_at** `nullable, string`

When a `budget_limit` connection serves again.

Format: `date-time`

**budget** `[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](https://docs.dari.dev/link/usage-and-budgets.md#budgets).

**properties**

**window\_minutes** `integer`

The rolling window the cap covers.

Possible values: `300` (five hours), `10080` (a week)

**max\_tokens** `integer`

The most tokens your app may use in the window.

**used\_tokens** `integer`

The tokens your app used in the window.

**resets\_at** `nullable, string`

When the window is back under its cap. Set only at the cap.

**plans** `[object]`

The plans and API keys your user shared.

**properties**

**id** `string`

The identifier of the plan or key.

**kind** `string`

The kind of plan, or `api_key`.

Possible values: `openai_codex`, `anthropic_claude_code`, `github_copilot`, `xai_grok`, `opencode_go`, `meta_muse`, `vercel_token_pass`, `api_key`

**title** `string`

What to call it on screen, such as `ChatGPT`, `Claude`, or `OpenRouter`.

**plan** `string`

The plan's name, such as `ChatGPT Plus/Pro` or `OpenRouter API Key`.

**label** `string`

Which one it is: the plan's account, or `Key ending 4f2a`.

**account\_email** `nullable, string`

The plan's account. `null` for an API key.

**provider** `string`

For an API key, the provider it is a key for, such as `openrouter`.

**model\_prefix** `string`

For an OpenRouter or Vercel AI Gateway key: it serves any model named with this prefix, such as `openrouter/`, and `models` lists none.

**serves** `string`

Which apps the plan serves.

Possible values: `any_app`, `claude_code_only`, `muse_code_only`

**state** `string`

Whether the plan can serve now.

`ready`: It can.

`plan_limit`: The plan is at its own usage limit, until `available_at`.

**available\_at** `nullable, string`

When a `plan_limit` plan serves again, when known.

**usage** `[object]`

The quota windows the plan last reported, each with `window_minutes`, the share used as `utilization` from 0 to 1, and `resets_at`. Empty until the plan has served a request through Dari.

**models** `[object]`

The models the plan serves, each with the `id` a request uses and its display `name`.

**models** `[object]`

The models your app can name now, each with the `id` a request uses and its display `name`.

**routes** `boolean`

Whether `dari/routing` serves your app now.

**manage\_url** `string`

Dari's page for this connection, where your user sees its usage, sets its budget, and disconnects.

**app\_name** `string`

Your app's name, as Link shows it.

**client\_id** `string`

Your app's `client_id`.

**created\_at** `string`

When your user connected.

Format: `date-time`

```json Response Object theme={null}
{
  "grant_id": "lgr_0deb6bbf7672493ba67ef0a9edfb0e8c",
  "client_id": "lnk_60271c0b990646d6a02d251cf73ed6af",
  "app_name": "My App",
  "created_at": "2026-11-18T20:48:15.549Z",
  "scope": "route",
  "budget": [
    { "window_minutes": 10080, "max_tokens": 500000, "used_tokens": 312000, "resets_at": null }
  ],
  "state": "ready",
  "available_at": null,
  "manage_url": "https://routing.dari.dev/v1/link/connections#lgr_0deb6bbf7672493ba67ef0a9edfb0e8c",
  "plans": [
    {
      "state": "ready",
      "available_at": null,
      "id": "cred_d6e1a1ee3b5a4da2b380afdece979032",
      "kind": "openai_codex",
      "title": "ChatGPT",
      "plan": "ChatGPT Plus/Pro",
      "label": "me@example.com",
      "account_email": "me@example.com",
      "serves": "any_app",
      "unavailable_until": null,
      "usage": [{ "window_minutes": 300, "utilization": 0.42, "resets_at": "2026-11-18T23:10:00.000Z" }],
      "models": [{ "id": "dari/model/openai/gpt-5.5", "name": "GPT-5.5" }]
    },
    {
      "state": "ready",
      "available_at": null,
      "id": "key_7a964389227d4a2c9849746916fc665e",
      "kind": "api_key",
      "title": "OpenRouter",
      "provider": "openrouter",
      "model_prefix": "openrouter/",
      "plan": "OpenRouter API Key",
      "label": "Key ending 4f2a",
      "account_email": null,
      "serves": "any_app",
      "unavailable_until": null,
      "usage": [],
      "models": []
    }
  ],
  "models": [{ "id": "dari/model/openai/gpt-5.5", "name": "GPT-5.5" }],
  "routes": true
}
```

***

## 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](https://docs.dari.dev/link/usage-and-budgets.md).

One request's usage is at `GET /v1/link/usage/requests/<X-Request-Id>`, in the same shape.

#### Request Fields

**tag** `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`.

**since** `string`

Only requests received at or after this time.

Format: `date-time`

**until** `string`

Only requests received before this time.

Format: `date-time`

**group\_by** `string`

`tag:<key>` also totals the usage per value of that tag, in `by_tag`.

```ts Node theme={null}
import { usage } from "@mupt-ai/dari-gateway/link/client";

const report = await usage({
  gatewayUrl: DARI_GATEWAY_URL,
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
  refreshToken,
  tags: { run: "r1" },              // optional filter
  since: new Date(Date.now() - 86_400_000),
  groupByTag: "trial",              // optional: totals per trial
});
```

```python Python theme={null}
import requests
from datetime import datetime, timedelta, timezone

report = requests.get(f"{DARI_GATEWAY_URL}/v1/link/usage",
    params={
        "tag": "run=r1",              # optional filter
        "since": (datetime.now(timezone.utc) - timedelta(days=1)).isoformat(),
        "group_by": "tag:trial",      # optional: totals per trial
    },
    headers={"Authorization": f"Bearer {access_token}"}).json()
```

```go Go theme={null}
query := url.Values{
	"tag":      {"run=r1"}, // optional filter
	"since":    {time.Now().Add(-24 * time.Hour).UTC().Format(time.RFC3339)},
	"group_by": {"tag:trial"}, // optional: totals per trial
}
endpoint := dariGatewayURL + "/v1/link/usage?" + query.Encode()
req, _ := http.NewRequest("GET", endpoint, nil)
req.Header.Set("Authorization", "Bearer "+accessToken)
report, err := http.DefaultClient.Do(req) // the body is the report, as JSON
```

```bash cURL theme={null}
curl "$DARI_GATEWAY_URL/v1/link/usage?tag=run%3Dr1&since=2026-01-01T00:00:00Z&group_by=tag:trial" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

#### Response Fields

**requests** `integer`

The number of requests.

**errors** `integer`

The requests the provider or Dari failed. They count in `requests` too.

**input\_tokens** `integer`

Input tokens, excluding cache reads and writes, whatever protocol the requests spoke.

**output\_tokens** `integer`

Output tokens.

**cache\_read\_tokens** `integer`

Tokens read from the prompt cache.

**cache\_write\_tokens** `integer`

Tokens written to the prompt cache.

**by\_model** `[object]`

The same totals per `model` and `thinking` level served, most requests first.

**by\_tag** `[object]`

With `group_by`: the same totals per `value` of that tag. `value` is `null` for requests without it.

**complete\_through** `nullable, string`

Every request received before this time is counted. `null` when the gateway cannot tell.

```json Response Object theme={null}
{
  "requests": 1,
  "errors": 0,
  "input_tokens": 10,
  "output_tokens": 2,
  "cache_read_tokens": 4,
  "cache_write_tokens": 0,
  "complete_through": "2026-11-18T20:47:46.181Z",
  "by_model": [
    {
      "model": "openai/gpt-5.5",
      "thinking": "high",
      "requests": 1,
      "errors": 0,
      "input_tokens": 10,
      "output_tokens": 2,
      "cache_read_tokens": 4,
      "cache_write_tokens": 0
    }
  ],
  "by_tag": [
    {
      "value": "7",
      "requests": 1,
      "errors": 0,
      "input_tokens": 10,
      "output_tokens": 2,
      "cache_read_tokens": 4,
      "cache_write_tokens": 0
    }
  ]
}
```

***

## 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

**token** `string` *required*

Any token of the connection. Use the `refresh_token`.

**client\_id** `string`

Your app's `client_id`. Required for an app without a secret.

```ts Node theme={null}
import { revoke } from "@mupt-ai/dari-gateway/link/client";

await revoke({
  gatewayUrl: DARI_GATEWAY_URL,
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
  token: refreshToken,
});
// Then delete the refresh token from your database.
```

```python Python theme={null}
import requests

requests.post(f"{DARI_GATEWAY_URL}/v1/link/revoke",
    auth=(CLIENT_ID, CLIENT_SECRET),
    data={"token": refresh_token})
# Then delete the refresh token from your database.
```

```go Go theme={null}
form := url.Values{"token": {refreshToken}}
req, _ := http.NewRequest("POST", dariGatewayURL+"/v1/link/revoke",
	strings.NewReader(form.Encode()))
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
req.SetBasicAuth(clientID, clientSecret)
if _, err := http.DefaultClient.Do(req); err != nil {
	return err
}
// Then delete the refresh token from your database.
```

```bash cURL theme={null}
curl -X POST $DARI_GATEWAY_URL/v1/link/revoke -u "$CLIENT_ID:$CLIENT_SECRET" -d token=$REFRESH_TOKEN
```

#### 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](https://console.dari.dev) 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

**client\_name** `string` *required*

The name of your app, as Link shows it.

**redirect\_uris** `[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](https://docs.dari.dev/link/run-a-gateway.md).

Min items: `1`

**token\_endpoint\_auth\_method** `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.

```bash cURL theme={null}
curl -X POST $DARI_GATEWAY_URL/v1/link/register \
  -H "authorization: Bearer $DARI_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "client_name": "My App",
    "redirect_uris": ["https://myapp.com/dari/callback"],
    "token_endpoint_auth_method": "client_secret_basic"
  }'
```

#### Response Fields

**client\_id** `string`

Your app's public identifier.

**client\_secret** `string`

Your server's private key. Returned only for a Server app, and only this once. Store it like a password.

```json Response Object theme={null}
{
  "client_id": "lnk_e03370fb98eb46529fbe340238b97ea5",
  "client_secret": "dlk_cs_xtT5tcGQh5LOPW-HOZV9B6is6MjZvcKYfsqX78E_Z5I",
  "client_name": "My App",
  "redirect_uris": ["https://myapp.com/dari/callback"],
  "token_endpoint_auth_method": "client_secret_basic"
}
```

***

## Authorize

`GET /v1/link/authorize`

The Link page itself. [`DariLink.open`](https://docs.dari.dev/link/web#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

**response\_type** `string` *required*

`code`

**client\_id** `string` *required*

Your app's `client_id`.

**redirect\_uri** `string` *required*

One of your app's registered redirect URIs, exactly as registered.

**state** `string` *required*

A random value your app makes. Link returns it with the code: check that it matches.

**code\_challenge** `string` *required*

The PKCE challenge: the base64url SHA-256 of the verifier your app keeps.

**code\_challenge\_method** `string` *required*

`S256`

**response\_mode** `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`.

**plans** `string`

The kinds of plan to offer, separated by spaces. See [`plans`](https://docs.dari.dev/link/web#open).

**key\_providers** `string`

The providers whose API keys your app can use, separated by spaces.

**client** `string`

The coding agents your app runs itself, separated by spaces. See [`clients`](https://docs.dari.dev/link/web#open).

**grant\_id** `string`

An existing connection, to open in [update mode](https://docs.dari.dev/link/manage-connections.md#update-mode).

```text Authorize URL theme={null}
https://routing.dari.dev/v1/link/authorize
  ?response_type=code
  &client_id=lnk_…
  &redirect_uri=https://myapp.com/dari/callback
  &state=…
  &code_challenge=…
  &code_challenge_method=S256
```

***

## Token Prefixes

| Prefix | Token |
| - | - |
| `dlk_code_` | Code (10 minutes, single-use) |
| `dlk_at_` | Access token (1 hour) |
| `dlk_rt_` | Refresh token |
| `dlk_ct_` | Child token (up to 12 hours) |
| `dlk_cs_` | Client secret |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.