---
title: "Create an API key"
method: POST
path: "/v1beta/api-keys"
tags: ["API Keys"]
---

# Create an API key

`POST /v1beta/api-keys`

Creates a new API key for the specified organization. The secret is only returned once in the response and cannot be retrieved later.

## Request body

- CreateApiKeyRequest — CreateApiKeyRequest contains the data needed to create a new API key.
  - `expires_at` string, date-time — Expiration timestamp. If not set, the key does not expire. When set, must be in the future and within 1 year. Security note: Keys without expiration should be rotated periodically. timestamp.gt_now = true timestamp.within = 8760h0m0s
  - `name` string, required — Human-readable name for the key (e.g., "Production", "Staging").
  - `organization_id` string, required — Organization ID to create the key for. Pattern: org_[0-9a-hjkmnp-tv-z]{26}

## Response `200`

Success

- CreateApiKeyResponse — CreateApiKeyResponse contains the newly created API key and its secret.
  - `api_key` ApiKey, required — ApiKey represents an authentication credential for programmatic API access.
    - `created_at` string, date-time, required — Timestamp when the key was created.
    - `expires_at` string, date-time — Expiration timestamp. If set, the key becomes invalid after this time.
    - `id` string, required — Unique ID for the API key. Pattern: key_[0-9a-hjkmnp-tv-z]{26}
    - `is_active` boolean, required — Whether the key is currently active (not revoked and not expired). Computed: is_active = (revoked_at == null) && (expires_at == null || expires_at > now())
    - `key_prefix` string, required — Truncated key prefix for identification in UI (e.g., "ffy_prod_01jd4h5..."). Shows the first 16 characters for better uniqueness while maintaining security.
    - `name` string, required — Human-readable name for the key (e.g., "Production", "Staging").
    - `organization_id` string, required — ID of the organization this key belongs to. Pattern: org_[0-9a-hjkmnp-tv-z]{26}
    - `revoked_at` string, date-time — Timestamp when the key was revoked. Null if the key has not been revoked.
  - `secret` string, required — The API key secret. This is only returned once and cannot be retrieved later. Format: ffy_{env}_{base32_uuid7}{base62_random} - env: "prod" or "test" - base32_uuid7: 26 chars (TypeID base32 alphabet: 0-9a-hjkmnp-tv-z) - base62_random: 43 chars (0-9A-Za-z) Store this value securely - it will not be shown again. SECURITY WARNING: This field must NEVER be logged. Handlers must redact secrets from all logs.

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication failed - missing or invalid API key
- `403` — Authorization failed - valid key but insufficient permissions
- `404` — Resource not found
- `429` — Too many requests
- `500` — Internal server error

---

[API](https://skmtc.net/factify-inc/apis/factify-api.md) · [All operations](https://skmtc.net/factify-inc/apis/factify-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/factify-inc/factify-api/revisions/8baabdfb82bf/schema)