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

# Update API Key

> Update an API key's name, scopes, expiry, or metadata

## Overview

Updates an API key. The raw key value is never affected; use [Rotate API Key](/api-reference/administration/rotate-api-key) to issue new credentials. Metadata uses **merge semantics** (`null` values remove keys). Scope changes are subject to escalation prevention: you cannot grant scopes that the calling key does not already hold. System keys cannot be modified, and revoked or expired keys return `404`.

Requires the `api-keys:manage` scope and an `Idempotency-Key` header; see [Idempotency](/api-reference/introduction#idempotency).

## Path Parameters

<ParamField path="id" type="string" required>
  API key ID (`key_...`).
</ParamField>

## Request Body

<ParamField body="name" type="string">New name (1-255 characters).</ParamField>
<ParamField body="scopes" type="string[]">Replacement scope list (at least one). Subject to escalation prevention.</ParamField>
<ParamField body="expires_at" type="string">New expiry as an ISO 8601 timestamp, or `null` to clear. Must be in the future.</ParamField>
<ParamField body="metadata" type="object">Metadata patch. Values may be strings or `null`.</ParamField>

## Response

Returns the updated API key, with the same fields as [Get API Key](/api-reference/administration/get-api-key).

<ResponseExample>
  ```json theme={null}
  {
    "id": "key_Mc2eF6gH",
    "object": "api_key",
    "name": "Aurora Digital production (renamed)",
    "prefix": "sig_7kMn2pQr",
    "scopes": ["trademarks:read"],
    "rate_limit_tier": "standard",
    "status": "active",
    "expires_at": null,
    "last_used_at": "2026-06-11T14:30:00.000Z",
    "metadata": { "owner": "platform-team" },
    "revoked_at": null,
    "created_by": "key_Lb1dE5fG",
    "created_at": "2026-01-05T12:00:00.000Z",
    "updated_at": "2026-06-12T10:00:00.000Z",
    "request_id": "req_yR4iJ0kL"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.signa.so/v1/organization/api-keys/key_Mc2eF6gH" \
    -H "Authorization: Bearer sig_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: rename-key-Mc2eF6gH-2026-06-12" \
    -d '{
      "name": "Aurora Digital production (renamed)",
      "scopes": ["trademarks:read"],
      "metadata": { "owner": "platform-team" }
    }'
  ```

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";

  const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

  const updated = await signa.organization.apiKeys.update("key_Mc2eF6gH", {
    name: "Aurora Digital production (renamed)",
    scopes: ["trademarks:read"],
    metadata: { owner: "platform-team" },
  });
  ```
</CodeGroup>

## Errors

| Status | Type               | Description                                                                                    |
| ------ | ------------------ | ---------------------------------------------------------------------------------------------- |
| 400    | `validation_error` | Empty name, unknown scope, `expires_at` not in the future, or missing `Idempotency-Key` header |
| 401    | `unauthorized`     | Missing or invalid API key                                                                     |
| 403    | `forbidden`        | API key lacks `api-keys:manage`, target key is a system key, or scope escalation attempted     |
| 404    | `not_found`        | API key does not exist, belongs to another org, or is revoked or expired                       |

## Related Endpoints

* [Get API Key](/api-reference/administration/get-api-key)
* [Delete API Key](/api-reference/administration/delete-api-key)
* [Rotate API Key](/api-reference/administration/rotate-api-key)