> ## 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.

# Create API Key

> Generate a new API key for the organization

## Overview

Creates a new API key for your organization. The full key secret is returned only once in the response; it cannot be retrieved again. Store it securely immediately after creation.

You can assign a name for identification, specific scopes to limit access, an optional expiration date, and key-value metadata. You cannot grant scopes the calling key does not itself hold, and an organization can have at most 25 active keys.

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

## Request Body

<ParamField body="name" type="string" required>
  Human-readable name for the key, 1-255 characters (e.g. "Production Backend").
</ParamField>

<ParamField body="scopes" type="string[]" required>
  Authorized scopes (1-20 values, must be a subset of the calling key's scopes):

  | Scope                 | Grants access to                                                                                                                          |
  | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
  | `trademarks:read`     | Trademark records, owners, attorneys, firms, proceedings — all public catalog data                                                        |
  | `events:read`         | Event feed (`/v1/events`). Plan-gated. Reserved surface — not yet populated (returns empty lists today); use `/v1/alerts` for monitoring. |
  | `portfolios:manage`   | Customer-owned resources: portfolios, saved searches, watches, alerts, webhooks                                                           |
  | `api-keys:manage`     | API key creation, rotation, update, and revocation                                                                                        |
  | `organization:manage` | Organization settings (e.g. renaming the organization)                                                                                    |
  | `billing:read`        | Usage, plan, and request log endpoints                                                                                                    |
</ParamField>

<ParamField body="expires_at" type="string | null">
  Optional ISO 8601 timestamp for key expiration. Must be in the future. Omit or pass `null` for a non-expiring key.
</ParamField>

<ParamField body="metadata" type="object">
  Optional key-value metadata (string values, max 50 keys).
</ParamField>

## Response

Returns the full API key object plus the one-time `key` secret, flat at the top level.

<ResponseField name="id" type="string">Key ID (`key_*`).</ResponseField>
<ResponseField name="object" type="string">Always `api_key`.</ResponseField>
<ResponseField name="name" type="string">Key name.</ResponseField>
<ResponseField name="key" type="string">Full API key secret. This is the only time it is returned.</ResponseField>
<ResponseField name="prefix" type="string">First 12 characters of the key, for identification.</ResponseField>
<ResponseField name="scopes" type="string[]">Authorized scopes.</ResponseField>
<ResponseField name="rate_limit_tier" type="string">Rate limit tier label for the key. `standard` by default.</ResponseField>
<ResponseField name="status" type="string">Lifecycle state: `active`, `expired`, or `revoked`. Always `active` on creation.</ResponseField>
<ResponseField name="expires_at" type="string | null">Expiry timestamp, or `null`.</ResponseField>
<ResponseField name="last_used_at" type="string | null">Always `null` on creation.</ResponseField>
<ResponseField name="metadata" type="object">Key-value metadata.</ResponseField>
<ResponseField name="revoked_at" type="string | null">Always `null` on creation.</ResponseField>
<ResponseField name="created_by" type="string">ID of the API key that created this key.</ResponseField>
<ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
<ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
<ResponseField name="request_id" type="string">Unique request identifier for support and debugging.</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "id": "key_Pe5hI9jK",
    "object": "api_key",
    "name": "Aurora Digital analytics",
    "key": "sig_69f99181efdb8d205c86878c5f232ee0722f22750b2cc25b",
    "prefix": "sig_69f99181",
    "scopes": ["trademarks:read", "billing:read"],
    "rate_limit_tier": "standard",
    "status": "active",
    "expires_at": null,
    "last_used_at": null,
    "metadata": {},
    "revoked_at": null,
    "created_by": "key_Mc2eF6gH",
    "created_at": "2026-06-12T16:00:00.000Z",
    "updated_at": "2026-06-12T16:00:00.000Z",
    "request_id": "req_wP2gH8iJ"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.signa.so/v1/organization/api-keys" \
    -H "Authorization: Bearer sig_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: create-analytics-key-2026-06-12" \
    -d '{
      "name": "Aurora Digital analytics",
      "scopes": ["trademarks:read", "billing:read"]
    }'
  ```

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

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

  const apiKey = await signa.organization.apiKeys.create({
    name: "Aurora Digital analytics",
    scopes: ["trademarks:read", "billing:read"],
  });

  // Store apiKey.key securely: it won't be returned again
  console.log("New key:", apiKey.key);
  ```
</CodeGroup>

## Errors

| Status | Type                     | Description                                                                                     |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------------- |
| 400    | `validation_error`       | Missing `name`, unknown scope values, invalid `expires_at`, or missing `Idempotency-Key` header |
| 401    | `unauthorized`           | Missing or invalid API key                                                                      |
| 403    | `forbidden`              | API key lacks `api-keys:manage`, or the request grants scopes the calling key does not hold     |
| 409    | `conflict`               | The `Idempotency-Key` was already used with a **different** request body                        |
| 409    | `idempotency_processing` | A request with the same `Idempotency-Key` is still in flight                                    |
| 429    | `rate_limited`           | Too many requests, or the organization already has 25 active keys                               |

<Note>
  Retrying with the same `Idempotency-Key` and the same body replays the cached response, including the same `key` secret, so an ambiguous network failure never mints a second credential. Duplicate key **names** are allowed and do not 409.
</Note>

## Related Endpoints

* [List API Keys](/api-reference/administration/list-api-keys), view all keys
* [Rotate API Key](/api-reference/administration/rotate-api-key), rotate an existing key
* [Get Current Organization](/api-reference/administration/get-me), organization profile