Skip to main content
POST
/
v1
/
api-keys
Create an API key
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'Production Key', expires_at: '2026-07-15T10:30:00Z'})
};

fetch('https://api.factify.com/v1/api-keys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "key_01h2xcejqtf2nbrexx3vqjhp41",
  "org_id": "org_01h2xcejqtf2nbrexx3vqjhp41",
  "name": "Production Key",
  "prefix": "ffy_prod_01kdx2z2...",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:35:00Z",
  "is_active": true,
  "key": "ffy_prod_EXAMPLE_KEY_DO_NOT_USE",
  "expires_at": "2026-01-15T10:30:00Z",
  "revoked_at": "2023-11-07T05:31:56Z",
  "revoked_by": "usr_01h2xcejqtf2nbrexx3vqjhp41",
  "revoked_comment": "rotated"
}

Documentation Index

Fetch the complete documentation index at: https://developers.factify.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Bearer authentication using a factapi-issued API key (ffy_<env>_<base32_uuid><base62_random>). Cookie-based sessions are accepted automatically by user-facing endpoints but are not surfaced as an OpenAPI auth scheme.

Headers

​
X-Factify-Organization-Id
string

Optional. Factify-staff acting-as override: when set, factapi resolves the request against this organization instead of the session-bound one. Honored only for callers with @factify.com emails; non-staff requests carrying this header are rejected with 403. The value is a typed org id (e.g. org_01h2xcejqtf2nbrexx3vqjhp41).

Pattern: ^org_[0-9a-hjkmnp-tv-z]{26}$
Example:

"org_01h2xcejqtf2nbrexx3vqjhp41"

Body

application/json

Fields required to create a new API key.

​
name
string
required

Human-readable name for the key (e.g. "Production", "Staging").

Example:

"Production Key"

​
expires_at
string<date-time>

Optional expiration timestamp. If not set, the key does not expire. When set, must be in the future and within one year of now.

Security note: keys without expiration should be rotated periodically.

Example:

"2026-07-15T10:30:00Z"

Response

The newly created API key, including the full secret (returned exactly once).

The newly created API key, including the full secret. The secret (key) is only returned in this response and cannot be retrieved later — store it securely now.

​
id
string
required

Unique TypedID for the API key. Pattern: key_[0-9a-hjkmnp-tv-z]{26}

Example:

"key_01h2xcejqtf2nbrexx3vqjhp41"

​
org_id
string
required

TypedID of the organization this key belongs to. Pattern: org_[0-9a-hjkmnp-tv-z]{26}

Example:

"org_01h2xcejqtf2nbrexx3vqjhp41"

​
name
string
required

Human-readable name for the key.

Example:

"Production Key"

​
prefix
string
required

Truncated key prefix for identification in UI. Safe to log.

Example:

"ffy_prod_01kdx2z2..."

​
created_at
string<date-time>
required

Timestamp when the key was created.

Example:

"2025-01-15T10:30:00Z"

​
updated_at
string<date-time>
required

Timestamp of the last metadata update.

Example:

"2025-01-15T10:35:00Z"

​
is_active
boolean
required

Whether the key is currently usable for authentication.

Example:

true

​
key
string
required

The full API key token, format ffy_{env}_{base32_uuid}{base62_random} (per ADR-008). Only returned in this response — store it securely.

SECURITY: never log this value; redact it from any persisted request or response payloads.

Example:

"ffy_prod_EXAMPLE_KEY_DO_NOT_USE"

​
expires_at
string<date-time>

Expiration timestamp. Absent if the key does not expire.

Example:

"2026-01-15T10:30:00Z"

​
revoked_at
string<date-time>

Timestamp when the key was revoked. Absent on creation.

​
revoked_by
string

TypedID of the user who revoked the key. Absent on creation. Pattern: usr_[0-9a-hjkmnp-tv-z]{26}

Example:

"usr_01h2xcejqtf2nbrexx3vqjhp41"

​
revoked_comment
string

Optional revocation reason. Absent on creation.

Example:

"rotated"