Skip to main content
POST
/
organizations
/
{organizationId}
/
api-keys
Create API key
curl --request POST \
  --url http://sandbox.mintlify.com/organizations/{organizationId}/api-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Production API Key",
  "description": "Used for production server",
  "scopes": [
    "read:user",
    "write:webhooks"
  ],
  "rateLimitPerMinute": 60,
  "rateLimitPerHour": 1000,
  "allowedIps": [
    "192.168.1.1",
    "10.0.0.0/24"
  ],
  "expiresAt": "2025-12-31T23:59:59Z"
}
'
Creates a new API key for programmatic access.

​
Permissions

User must be owner or admin.

​
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

​
Using API Keys

Include the API key in the X-API-Key header: 
curl -X GET http://localhost:3001/api/organizations/acme-corp \
  -H "X-API-Key: sk_..."

​
Example

curl -X POST http://localhost:3001/api/organizations/acme-corp/api-keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "description": "Key for production server"
  }'

​
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"

​
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
Example:
["read:user", "write:webhooks"]
​
rateLimitPerMinute
number

Rate limit per minute

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

60

​
rateLimitPerHour
number

Rate limit per hour

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

1000

​
allowedIps
string[]

Allowed IP addresses (CIDR notation supported)

Example:
["192.168.1.1", "10.0.0.0/24"]
​
expiresAt
string

Expiration date

Example:

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

Response

API key created successfully. Save the plain key securely!