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

# Change this connection's access

`PATCH /connection`

## Request

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

Change what this AI-assistant connection may do, from the chat, after the
person has said yes. Send `grants`, one per business to change
(`organization_id`, or null for the person's own account) with `access`
`none`, `read` or `write`, and or `new_organization_access` for businesses
the person joins later (`none`, `read`, or `role`). Applies at once; the
connection stays live. The person is emailed what changed, with the link
to undo it.

Use it when a write was refused with code `insufficient_access` and the
person wants to allow it: offer to switch this connection to read and
write in that business, and call this only once they agree in the chat.
A grant can never exceed the person's own role in that business (owner,
admin and manager can allow writes; contractor and viewer only reads); a
422 says which. Every gate a write passes applies here too: a connection
without the `write` scope (one made before 2026-10-09, or a client that
asked for less) is refused with code `insufficient_access`, and the person
widens it from the `manage_url` link instead. There is no id: a token
changes itself only. Only the grants named change; the others stand.

## Request body

- OauthTokenUpdateAttributes: Manage connection write in flat shape (Content-Type application/json). Send only what changes.
  - `new_organization_access` 'none' | 'read' | 'role'
  - `grants` OauthTokenGrant[]
    - `organization_id` string, uuid, nullable: The business; null is the person's own account.
    - `access` 'none' | 'read' | 'write', required

## Response `200`

The connection, with its grants as they now stand 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; or a grant names a business that does not exist.
- `422`: A grant exceeds the person's role, or names a business they are not in.

---

[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/06540345bbbc?raw)