---
title: "Read this connection's access"
method: GET
path: "/connection"
tags: ["Connection"]
---

# Read this connection's access

`GET /connection`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/connection`
- Auth: HTTP bearer

What this AI-assistant connection may do, read by the connection itself:
the token's grants, and under `meta.access` one row per business the
person belongs to with their role there (`permission`), the access today
(`none`, `read` or `write`), the most that role can grant (`most_allowed`)
and, when that is less than write, the `reason`; the last row is the
person's own account. Call it before offering to change access, so you
can say what is possible: an owner, admin or manager can allow read and
write; a contractor or viewer stays read only, and only a role change by
the business lifts that.

A connection starts with read and write wherever the person's role allows
it (since 2026-10-09). Read-only access means the person narrowed it, or
connected before that date. There is no id: a token reads itself only. A
session or an API key is a 404 here.

## Response `200`

The connection, with its grants and the access overview in `meta`.

- ConnectionResponseAttributes
  - `data` OauthTokenModelAttributes: Single token in attributes-adapter shape (Accept application/json).
    - `id` string
    - `type` string
    - `kind` 'web_or_mobile' | 'api' | 'mcp'
    - `name` string, nullable
    - `application_name` string
    - `application_uid` string
    - `scopes` string
    - `organization_id` string, uuid, nullable
    - `created_at` string, date-time
    - `expires_at` string, date-time, nullable
    - `current` boolean
    - `last_used_at` string, date-time, nullable: When an AI-assistant connection last made a request, to the minute; null until it has, and on sessions and api-key tokens.
    - `new_organization_access` 'none' | 'read' | 'role': An AI-assistant connection's access in a business the person joins later. `role` is read and write where the role allows it, read only elsewhere.
    - `grants` OauthTokenGrant[]: An AI-assistant connection's grants, one per business plus the person's own account (`organization_id` null). Empty on a session, an api-key token, or a connection made before grants existed, which acts on its scopes alone.
      - `organization_id` string, uuid, nullable: The business; null is the person's own account.
      - `access` 'none' | 'read' | 'write', required
  - `meta` ConnectionMeta
    - `access` ConnectionAccessRow[]: One row per business the person belongs to, then their own account.
      - `organization_id` string, nullable: The business; null is the person's own account.
      - `name` string: The business's name, or "Your own account".
      - `permission` string, nullable: The person's role in the business (owner, admin, manager, contractor, viewer); null on their own account.
      - `access` 'none' | 'read' | 'write': What the connection may do there today.
      - `most_allowed` 'read' | 'write': The most the person's role can grant there.
      - `reason` string, nullable: Why not more, when `most_allowed` is read; null otherwise.

## Other responses

- `401`: Unauthorized
- `404`: The bearer is a session or an API key, not an AI-assistant connection.

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) · [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/4bedbc1c784c?raw)