---
title: "Update Oauth Token"
method: PATCH
path: "/oauth-tokens/{id}"
tags: ["OauthTokens"]
---

# Update Oauth Token

`PATCH /oauth-tokens/{id}`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/oauth-tokens/{id}`
- Auth: HTTP bearer

Change what an AI-assistant (MCP) connection may do (Manage
connection): `grants`, one per business — `organization_id` null is
your own account — each `none`, `read` or `write`, and
`new_organization_access`, its default in a business you join later
(`none`, `read`, or `role`: read and write where your role allows it,
read only elsewhere). Applies at once; the connection stays live.

A grant can never exceed your own role in that business (owner, admin
and manager can grant writes; contractor and viewer only reads); a 422 says
which. A self-registered assistant is issued `public read write` and its
grants are seeded at consent to match your role (read and write where you
are an owner, admin or manager, read only elsewhere, read and write on your
own account); what the grants say is what it can do, from its next request.
A connection consented without `write` (made before 2026-10-09, or a client
that asked for less) gains the scope with its first `write` grant and loses
it with the last. Only the
connection's own person may call this, and only for an `mcp` token.
A connection made before grants existed gets its first grants seeded
from your roles on the first update.

## Path parameters

- `id` string, required

## 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 token, with its grants as they now stand.

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

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: A grant exceeds your role, or names a business you 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/a9136f78e9fb?raw)