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

# Manage Connections

> Let users change or remove what they shared.

## Check A Connection

Before a long job, see if the user's plans have room. It's cheap: no provider call.

```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"
```

The Python, Go, and cURL tabs send an access token. One call makes it from the refresh token you saved, and it lasts an hour: see [Refresh](https://docs.dari.dev/link/reference/http.md#refresh). The Node client makes and keeps it for you.

This is also what a connections list in your app shows: `connection.plans` for what the user shared, and `connection.manageUrl` (`manage_url` over HTTP) for Dari's page with its usage and limits.

Each plan in `connection.plans` has a `state`:

| `state` | Means |
| - | - |
| `ready` | Can serve now |
| `plan_limit` | Plan hit its own usage limit. `available_at` says when it's back |

The grant itself has a `state` too: `budget_limit` when your app used its token cap, until `connection.availableAt` (`available_at` over HTTP).

You don't have to check before every request: Dari refuses a request it can't serve and says when to retry.

## Update Mode

Your user can change what they shared without connecting again. Open Link with the connection's `grant_id`:

```js JavaScript theme={null}
DariLink.open({
  gatewayUrl: DARI_GATEWAY_URL,
  clientId: "lnk_…",
  redirectUri: "https://myapp.com/dari/callback",
  grantId: connection.grantId,
});
```

```text Authorize URL theme={null}
/v1/link/authorize?…&grant_id=lgr_…
```

The user sees what they shared, ticked, and can add or remove plans. The same `grantId` and refresh token keep working, so there is nothing new to store. If they open it from another browser, they get a fresh connection instead.

## Where Users Manage It

Users see every app they connected at `/v1/link/connections` on your gateway, in the browser they connected from: what each app shares and used, its token caps, and **Disconnect**. Link there with `grant.manage_url`.

## Disconnect

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

Every token for that connection stops working right away.

## When To Show Reconnect

A connection that is gone answers `401` with the code `grant_revoked`, and its refresh token answers `400 invalid_grant`. The Node client throws both as a `LinkError` whose `unlinked` is true:

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

try {
  await grant({
    gatewayUrl: DARI_GATEWAY_URL,
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
    refreshToken,
  });
} catch (error) {
  if (!(error instanceof LinkError && error.unlinked)) throw error;
  // The user disconnected: show your Reconnect button.
}
```

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

reply = requests.get(f"{DARI_GATEWAY_URL}/v1/link/grant",
    headers={"Authorization": f"Bearer {access_token}"})
disconnected = (reply.status_code == 401
    and reply.json()["error"]["code"] == "grant_revoked")
# If disconnected, show your Reconnect button.
```

```go Go theme={null}
req, _ := http.NewRequest("GET", dariGatewayURL+"/v1/link/grant", nil)
req.Header.Set("Authorization", "Bearer "+accessToken)
res, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
defer res.Body.Close()
var refused struct{ Error struct{ Code string } }
if res.StatusCode == http.StatusUnauthorized {
	json.NewDecoder(res.Body).Decode(&refused)
}
disconnected := refused.Error.Code == "grant_revoked"
// If disconnected, show your Reconnect button.
```

`linkFetch` is a `fetch`, so it returns Dari's response instead of throwing: check it for `401` and `grant_revoked` the same way.

| `error.code` | Means |
| - | - |
| `grant_revoked` | User or app disconnected |
| `invalid_grant` | The refresh token is no longer good |
| `not_linked` | A public client's storage holds no tokens |


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