> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update API Key

> Rename a company API key or change its permissions in place

Rename a company-scoped API key, replace its permissions, or both. The caller
must have the `api_keys:manage` permission.

The key value does not change. Added permissions apply on the next retry, so use
this instead of issuing a replacement key when a call fails with a missing-scope
error. Removed permissions may remain usable for up to five minutes while API
caches expire.

<Note>
  `preset` and `scopes` replace the whole permission selection rather than
  merging into it. Call [List API Keys](/api-reference/api-keys/list) first and
  send the full set you want.
</Note>

## Request

<ParamField path="apiKeyId" type="string" required>
  Exact API key ID returned by the list API keys endpoint.
</ParamField>

<ParamField body="name" type="string">
  New human-readable key name.
</ParamField>

<ParamField body="preset" type="string">
  Replacement permission preset: `full_access`, `read_only`, `agent_safe`,
  `ai_drafting`, `data_ingest_safe`, `data_ingest_automations`,
  `transactional_sender`, or `marketing_sender`.
</ParamField>

<ParamField body="scopes" type="string[]">
  Replacement explicit permission scopes. Overrides `preset` when provided.
</ParamField>

Provide at least one of `name`, `preset`, or `scopes`.

```bash theme={null}
curl -X PATCH "https://api.sequenzy.com/api/v1/api-keys/key_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-company-id: company_abc123" \
  -H "Content-Type: application/json" \
  -d '{"preset": "agent_safe"}'
```

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "apiKey": {
      "id": "key_abc123",
      "name": "Agent key",
      "prefix": "seq_live_abcd",
      "type": "company",
      "scopes": ["account:read", "subscribers:read", "subscribers:tag"],
      "permissions": {
        "preset": "custom",
        "fullAccess": false,
        "selectedScopeCount": 3,
        "currentScopeCount": 65,
        "description": "3 of 65 current permissions are enabled."
      },
      "deviceName": null,
      "lastUsedAt": "2026-08-04T09:12:00Z",
      "createdAt": "2026-07-17T10:30:00Z",
      "updatedAt": "2026-08-04T10:30:00Z",
      "isCurrent": false
    },
    "message": "API key permissions updated. Added permissions apply on the next retry; removed permissions may take up to five minutes to expire across API instances."
  }
  ```

  The response returns metadata only. It never includes the plain key or stored
  hash.

  ```json 400 theme={null}
  {
    "error": "Provide a name or permissions to update"
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "API key is missing required scope: api_keys:manage"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "API key not found"
  }
  ```
</ResponseExample>