---
title: "List linked identities"
method: GET
path: "/v1/assistant/grants"
tags: ["Assistant"]
---

# List linked identities

`GET /v1/assistant/grants`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/assistant/grants`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.naturali.ai/authorize`, token URL `https://api.naturali.ai/token`, scopes: `mcp:access`)

Lists the caller's assistant grants — one per channel identity that may operate their account. Grants belong to the account, so this is the caller's own set regardless of which projects they own.

## Query parameters

- `limit` integer
- `cursor` string

## Response `200`

A page of grants.

- AssistantGrantList
  - `data` AssistantGrant[], required
    - `id` string, required: Public grant ID (agr_ prefix).
    - `channel` 'discord' | 'whatsapp' | 'slack', required: The channel the linked identity lives on. The app is never a value here: a signed-in web session already *is* the identity, so it needs no grant.
    - `identifier` string, required: The channel identity as an address identifier (`discord:dm:<user_id>`, `whatsapp:dm:<phone>`), the one grammar channels use on the wire. One identity operates one account.
    - `display_name` string, nullable, required: The identity as its channel reported it, when it reported one — what a person recognizes instead of an opaque id. Null when the channel offers nothing better than the identifier.
    - `scopes` AssistantScope[], required: What the Assistant may do on the account. Deliberately coarse: the consent for a specific dangerous action is asked for when it happens, through the approval queue, rather than pre-granted here.
    - `status` 'active' | 'revoked', required: Whether the Assistant currently answers this identity.
    - `last_used_at` string, date-time, nullable, required: When the Assistant last acted under this grant; null if never.
    - `created_at` string, date-time, required
  - `next_cursor` string, nullable, required

## Other responses

- `401`: Missing or invalid credentials.

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)