Skip to main content
PUT
Update API key
Updates an API key’s settings.

Permissions

User must be owner or admin. Members receive 403 Forbidden.

What Can Be Updated

  • Name and description
  • Scopes (permissions)
  • Rate limits (per minute/hour). Send null to remove the key’s own limit and use your plan’s limit again
  • Allowed IP addresses
  • Expiration date
Note: The environment of a key (sandbox or production) cannot be changed; sending it returns 400 Bad Request. Create a new key in the other environment instead. Note: The API key value itself cannot be changed. To rotate a key, delete and create a new one.

Example

To remove the key’s own limits and use your plan’s limit:

Security Considerations

  • Changing scopes immediately affects API access
  • Rate limits are optional and can only lower your plan’s limit for this key. A key without them (or with them set to null) uses your plan’s limit. See Rate limiting.
  • Rate limit changes take effect on next request
  • IP restrictions are enforced in real-time

Authorizations

Authorization
string
header
required

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

Path Parameters

organizationId
string
required
id
string
required

Body

application/json
name
string

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"

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:
allowedIps
string[]

Allowed IP addresses (CIDR notation supported)

Example:
expiresAt
string

Expiration date

Example:

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

rateLimitPerMinute
number | null

Requests per minute for this key. Can only lower the plan limit. Send null to remove it and use the plan limit.

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

30

rateLimitPerHour
number | null

Requests per hour for this key. Send null to remove it and use the plan limit.

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

1000

Response

API key updated successfully