---
title: "Change a key’s name, permissions, expiry or scope; its value never changes"
method: PATCH
path: "/api/keys/{id}"
tags: ["auth"]
---

# Change a key’s name, permissions, expiry or scope; its value never changes

`PATCH /api/keys/{id}`

## Request

- Base URL: `https://www.orgo.ai`
- URL: `https://www.orgo.ai/api/keys/{id}`
- Auth: HTTP bearer

A key never makes or changes a key into more than it has itself: every group at or under its own level, its scope inside its own (a workspace key makes keys only for that workspace, never one for every workspace), and an expiry no later than its own when it expires. It changes or revokes only keys already within its own access, and only narrows itself; anything past that is 403 key_escalation. A signed in session may do anything to its own keys. A computer’s own key manages no keys (403 computer_key), nor does a key for one computer (403 computer_scope). An expired key answers 401 key_expired. Send only what changes. permissions: "full", "read_only" or an object of group to level. expires_in_days (1 to 365) or expires_at (a date within a year; null removes the expiry). workspace_id: a workspace, or null for every workspace. A computer’s own key is Orgo’s: 409 managed_key. A key for one computer keeps its computer: workspace_id or computer_id is 400 computer_scope_fixed.

## Request body

- ApiKeyUpdate
  - `name` string, nullable
  - `permissions` union
    - 'full' | 'read_only'
    - ApiKeyPermissions: A restricted key’s level per group: none, read or write (write includes read). A group left out is none. The API key permissions page lists every endpoint of each group.
      - `computers` 'none' | 'read' | 'write'
      - `control` 'none' | 'read' | 'write'
      - `files` 'none' | 'read' | 'write'
      - `templates` 'none' | 'read' | 'write'
      - `workspaces` 'none' | 'read' | 'write'
      - `members` 'none' | 'read' | 'write'
      - `secrets` 'none' | 'read' | 'write'
      - `ai` 'none' | 'read' | 'write'
      - `bops` 'none' | 'read' | 'write'
      - `billing` 'none' | 'read' | 'write'
      - `keys` 'none' | 'read' | 'write'
  - `expires_in_days` integer
  - `expires_at` string, date-time, nullable: null removes the expiry.
  - `workspace_id` string, uuid, nullable

## Response `200`

The key as it is now.

- ApiKey
  - `id` string, uuid
  - `name` string, nullable
  - `scope` 'account' | 'workspace' | 'computer': Where it reaches.
  - `workspace_id` string, uuid, nullable: The one workspace it reaches (a key for one computer: that computer’s); null for every workspace.
  - `key_prefix` string, nullable
  - `created_at` string, date-time
  - `last_used` string, date-time, nullable
  - `permissions` ApiKeyPermissions: A restricted key’s level per group: none, read or write (write includes read). A group left out is none. The API key permissions page lists every endpoint of each group.
    - `computers` 'none' | 'read' | 'write'
    - `control` 'none' | 'read' | 'write'
    - `files` 'none' | 'read' | 'write'
    - `templates` 'none' | 'read' | 'write'
    - `workspaces` 'none' | 'read' | 'write'
    - `members` 'none' | 'read' | 'write'
    - `secrets` 'none' | 'read' | 'write'
    - `ai` 'none' | 'read' | 'write'
    - `bops` 'none' | 'read' | 'write'
    - `billing` 'none' | 'read' | 'write'
    - `keys` 'none' | 'read' | 'write'
  - `access` 'full' | 'read_only' | 'custom'
  - `expires_at` string, date-time, nullable: null: never.
  - `expired` boolean: Past expires_at: listed until deleted, signs in nowhere (401 key_expired).
  - `computer_key` boolean: A computer’s own key, made and rotated by Orgo.
  - `computer` object, nullable: The computer a computer’s own key or a key for one computer is for.
    - `id` string
    - `name` string, nullable
  - `rotated_at` string, date-time, nullable: A computer’s own key: when its secret last changed.

## Other responses

- `400`: Nothing to change, invalid_permissions, invalid_expiry, reserved_name or computer_scope_fixed.
- `403`: key_escalation: the key is wider than the caller, or the change is more than it has. key_permission: no API keys write. account_key_required: a key for one computer, changed by a workspace key. client_key: a client account’s key.
- `404`: Not a key of the caller’s, or outside its scope.
- `409`: managed_key: a computer’s own key, a client’s key’s scope, a key moved into a client’s workspace, or Bops for iPhone’s key’s name.
- `429`: Thirty new or changed keys an hour.

## Changes

- **2026-11-01** `60e768a2bb9d`: 3 info
  - added the optional property `docs_url` to the response with the `403` status
  - added the optional property `next` to the response with the `403` status
  - added the optional property `retryable` to the response with the `403` status
- **2026-10-22** `8797b380fe7d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/orgo/apis/orgo-api/changes/api/keys/:id/patch.md)

---

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