API Keys¶

Create and manage API keys for programmatic access to the InvoicePDFs API.

Create API Key¶

POST /api/v1/api-keys

Request:

{
  "name": "production"
}

Field	Required	Default	Description
`name`	No	`"default"`	A label for this key (max 128 chars)

Response:

{
  "data": {
    "id": "key_01ABC",
    "name": "production",
    "api_key": "inv_live_abc123def456...",
    "last4": "f456",
    "created_at": "2026-07-20T10:00:00Z"
  }
}

Save your key

The full api_key value is only returned once at creation time. Store it securely — you will not be able to retrieve it again. Only the last4 digits are shown in subsequent responses.

Try it

List API Keys¶

GET /api/v1/api-keys

Response:

{
  "data": [
    {
      "id": "key_01ABC",
      "name": "production",
      "last4": "f456",
      "created_at": "2026-07-20T10:00:00Z",
      "revoked_at": null
    },
    {
      "id": "key_02DEF",
      "name": "staging",
      "last4": "a789",
      "created_at": "2026-07-15T08:00:00Z",
      "revoked_at": "2026-07-18T12:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

Revoked keys appear in the list with a non-null revoked_at timestamp.

Try it

Get API Key¶

GET /api/v1/api-keys/{api_key_id}

Fetch metadata for a single key. The secret is never returned — only the last4 digits, so you can identify a key without exposing it.

Response:

{
  "data": {
    "id": "key_01ABC",
    "name": "production",
    "last4": "f456",
    "created_at": "2026-07-20T10:00:00Z",
    "revoked_at": null
  }
}

Returns 404 not_found if the key doesn't exist or belongs to another account.

Try it

Update API Key¶

PATCH /api/v1/api-keys/{api_key_id}

Rename a key. Only the label changes — the secret and last4 stay the same.

Request:

{
  "name": "production-2026"
}

Field	Required	Description
`name`	Yes	New label for the key (max 128 chars)

Response:

{
  "data": {
    "id": "key_01ABC",
    "name": "production-2026",
    "last4": "f456",
    "created_at": "2026-07-20T10:00:00Z",
    "revoked_at": null
  }
}

Try it

Rotate API Key¶

POST /api/v1/api-keys/{api_key_id}/rotate

Rotate a key in one step: the existing key is revoked and a brand-new key with the same name is issued. Use this on a schedule, or immediately if a key may have leaked. As with creation, the full api_key is returned only once.

Response:

{
  "data": {
    "id": "key_09XYZ",
    "name": "production",
    "api_key": "inv_live_new789ghi012...",
    "last4": "i012",
    "created_at": "2026-08-06T09:00:00Z"
  }
}

The old key stops working immediately

Update your integration with the new api_key before rotating in production. Rotating an already-revoked key returns 409 conflict.

Try it

Revoke API Key¶

DELETE /api/v1/api-keys/{api_key_id}

Response:

{
  "data": {
    "revoked": true
  }
}

Revoked keys immediately stop working for authentication. This action cannot be undone — create a new key if needed.

Try it

Best Practices¶

Practice	Description
Rotate regularly	Create new keys periodically and revoke old ones
Use descriptive names	Label keys by environment or purpose (e.g. `production`, `ci-pipeline`)
One key per service	Use separate keys for each integration so you can revoke independently
Never commit keys	Store keys in environment variables or a secrets manager, never in source code