Skip to main content
POST
Create API key
Creates a new API key for programmatic access.

Permissions

Owners and admins can create keys for either environment. Members can create sandbox keys only. A member must send environment: "sandbox" explicitly; otherwise the API answers 403 with a message asking them to send it. A member can only request these scopes, any other returns 403: read:user, read:organization, read:customers, read:products, read:invoices and write:invoices. A closed organization also returns 403.

Environment

environment is optional and accepts sandbox or production. If omitted, owners and admins get a production key. The environment of a key never changes: Update API Key does not accept it. The response includes environment. Sandbox keys stamp CFDIs for testing only. They have no fiscal validity.
Known limitations of sandbox: invoices created with a sandbox key still fire your organization’s webhooks and can be emailed to the customer (TIM-294), and customers, products and webhooks are shared between sandbox and production (TIM-293).

How to get a sandbox key

  • Web: Configure → API Keys → “Create API Key” (Spanish UI: Configurar → Claves API → “Crear Clave API”). Owners and admins choose Sandbox or Production; members only get Sandbox.
  • API: POST /organizations/{organizationId}/api-keys with "environment": "sandbox" (example below).
  • SDK: client.apiKeys.create(orgId, { name, environment: "sandbox", scopes }).
  • CLI: timbrix api-keys create --org <id> --name <name> --environment sandbox.

Revocation

When a user leaves the organization, every API key they created there is revoked. When an owner or admin is demoted to member, their production keys and any key with scopes outside the member list are revoked. These revocations are recorded in the audit log.

Security

  • API keys are prefixed with sk_
  • Full key value is only shown once during creation
  • Store the key securely (never commit to git)
  • Keys are hashed before storage

Scopes

To read the API request log, create the key with the read:request-logs scope. To read the audit log, use read:audit-logs. Every scope must be one of the scopes listed in the request schema. An unknown scope returns 400 Bad Request, both here and in Update API Key.

Rate limits

rateLimitPerMinute and rateLimitPerHour are optional. If you omit them, the key uses your plan’s limit, and keeps following it when you change plans. Set them only to give this key a lower limit than your plan:
  • rateLimitPerMinute: requests per minute for this key. A value at or above your plan’s limit has no effect.
  • rateLimitPerHour: requests per hour for this key. Omit it for no hourly limit.
Requests with this key always count toward your organization’s plan limit. See Rate limiting.

Using API Keys

Include the API key in the X-API-Key header:

Example

Sandbox key:

Best Practices

  • Use descriptive names for keys
  • Create separate keys for different environments
  • Rotate keys regularly
  • Revoke unused keys immediately

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

organizationId
string
required

Body

application/json
name
string
required

API key name

Required string length: 3 - 50
Example:

"Production API Key"

description
string

API key description

Maximum string length: 200
Example:

"Used for production server"

environment
enum<string>
default:production

Environment of the key. Owners and admins default to 'production'. Members can only create 'sandbox' keys with a limited set of scopes, and must send environment: 'sandbox' explicitly.

Available options:
sandbox,
production
Example:

"sandbox"

scopes
enum<string>[]

API key scopes (permissions). Defaults to ['read:user'] if not provided

Available options:
read:user,
write:user,
read:organization,
write:organization,
read:members,
write:members,
read:webhooks,
write:webhooks,
read:api-keys,
write:api-keys,
read:invoices,
write:invoices,
read:customers,
write:customers,
read:products,
write:products,
read:request-logs,
read:audit-logs
Example:
rateLimitPerMinute
number

Requests per minute for this key. Optional: omitted means the plan limit. Can only lower the plan limit.

Required range: 1 <= x <= 10000
Example:

30

rateLimitPerHour
number

Requests per hour for this key. Optional: omitted means no hourly limit (only the plan limit applies).

Required range: 1 <= x <= 100000
Example:

1000

allowedIps
string[]

Allowed IP addresses (CIDR notation supported)

Example:
expiresAt
string

Expiration date

Example:

"2025-12-31T23:59:59Z"

Response

API key created successfully. Save the plain key securely!