Create API Key

Generate a new API key for the organization

POST /v1/organization/api-keys

Create API Key

cURL

curl --request POST \
  --url https://api.signa.so/v1/organization/api-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "scopes": [
    "<string>"
  ],
  "expires_at": "<string>"
}
'

{
  "id": "key_Pe5hI9jK",
  "object": "api_key",
  "name": "Analytics Dashboard",
  "key": "sig_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6",
  "prefix": "sig_a1b2",
  "scopes": ["trademarks:read", "billing:read"],
  "created_at": "2026-03-24T16:00:00Z",
  "expires_at": null,
  "request_id": "req_wP2gH8iJ"
}

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, and an optional expiration date.

Request Body

name · string · required

Human-readable name for the key (e.g., “Production Backend”)

scopes · string[] · required

Authorized scopes. The full registry:

Scope	Grants access to
trademarks:read	Trademark records, owners, attorneys, firms, proceedings — all public catalog data
events:read	Event feed (/v1/events). Plan-gated.
portfolios:manage	Customer-owned resources: portfolios, saved searches, watches, alerts, webhooks
watches:admin	Watch replay (POST /v1/watches/{id}/replay). Not self-service — request via [e-mail]
api-keys:manage	API key creation, rotation, update, and revocation
billing:read	Usage, plan, and log endpoints
admin	Superuser — implies every other scope. Internal tooling only; cannot be self-assigned

The legacy search:read scope is still accepted on old keys but is no longer issued — use trademarks:read.

expires_at · string

Optional ISO timestamp for key expiration. Omit for a non-expiring key.

Response

response · object

Show API key object

id · string

Key ID

name · string

Key name

key · string

Full API key secret. This is the only time the full key is returned.

prefix · string

Key prefix for identification

scopes · string[]

Authorized scopes

created_at · string

ISO timestamp

expires_at · string

ISO timestamp (null if no expiration)

{
  "id": "key_Pe5hI9jK",
  "object": "api_key",
  "name": "Analytics Dashboard",
  "key": "sig_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6",
  "prefix": "sig_a1b2",
  "scopes": ["trademarks:read", "billing:read"],
  "created_at": "2026-03-24T16:00:00Z",
  "expires_at": null,
  "request_id": "req_wP2gH8iJ"
}

Code Examples

cURL

curl -X POST https://api.signa.so/v1/organization/api-keys \
  -H "Authorization: Bearer sig_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-analytics-key-2026-06-12" \
  -d '{
    "name": "Analytics Dashboard",
    "scopes": ["trademarks:read", "billing:read"]
  }'

Errors

Status	Type	Description
400	validation_error	Missing name, invalid scope values, or missing Idempotency-Key header
401	unauthorized	Missing or invalid API key
403	forbidden	Insufficient permissions to create keys
409	conflict	The Idempotency-Key was already used with a different request body — generate a new key for each distinct request
409	idempotency_processing	A request with the same Idempotency-Key is still in flight — wait for it to finish, then retry
429	rate_limited	Too many requests

This endpoint is not exempt from idempotency. 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.

Related Endpoints

• List API Keys — view all keys
• Rotate API Key — rotate an existing key
• Get Current Organization — organization profile