API Keys

Manage API keys for tenant organizations.

List API Keys

GET /provisioning/organizations/:id/api-keys

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID

Headers

Header	Required	Description
X-Provisioning-Secret	Yes	Provisioning secret

Example

curl -X GET "https://api.courimax.com/api/provisioning/organizations/org-uuid/api-keys" \
  -H "X-Provisioning-Secret: your_provisioning_secret"

Response (200 OK)

[
  {
    "id": "key-uuid",
    "name": "Production Yango Key",
    "apiKey": "cmx_...masked...",
    "platform": "yango",
    "webhookUrl": "https://your-app.com/webhooks/courimax",
    "isActive": true,
    "createdAt": "2026-08-19T10:00:00.000Z",
    "lastUsedAt": "2026-08-19T14:30:00.000Z"
  }
]

Note: The full API key is masked for security. Use the create endpoint to generate new keys.

Create API Key

POST /provisioning/organizations/:id/api-keys

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID

Headers

Header	Required	Description
X-Provisioning-Secret	Yes	Provisioning secret
Content-Type	Yes	application/json

Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Descriptive name for the key
platform	string	No	Integration platform: yango, galaxis, floating_deli, or standard
webhookUrl	string	No	Webhook URL for notifications

Example

curl -X POST "https://api.courimax.com/api/provisioning/organizations/org-uuid/api-keys" \
  -H "X-Provisioning-Secret: your_provisioning_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Yango Key",
    "platform": "yango",
    "webhookUrl": "https://your-app.com/webhooks/courimax"
  }'

Response (201 Created)

{
  "id": "key-uuid",
  "name": "Production Yango Key",
  "apiKey": "cmx_generated_key_value_abc123",
  "platform": "yango",
  "webhookUrl": "https://your-app.com/webhooks/courimax",
  "isActive": true,
  "createdAt": "2026-08-19T10:00:00.000Z"
}

Important: The full API key is only returned once during creation. Store it securely.

Error Responses

400 Bad Request - Missing name

{
  "statusCode": 400,
  "message": "API key name is required",
  "error": "Bad Request"
}

409 Conflict - Key for platform already exists

{
  "statusCode": 409,
  "message": "A \"yango\" API key already exists for this tenant — rotate or revoke it instead.",
  "error": "Conflict"
}

Rotate API Key

Generate a new API key value while keeping the same key ID and metadata.

POST /provisioning/organizations/:id/api-keys/:keyId/rotate

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID
keyId	string	Yes	API key ID

Headers

Header	Required	Description
X-Provisioning-Secret	Yes	Provisioning secret

Example

curl -X POST "https://api.courimax.com/api/provisioning/organizations/org-uuid/api-keys/key-uuid/rotate" \
  -H "X-Provisioning-Secret: your_provisioning_secret"

Response (200 OK)

{
  "id": "key-uuid",
  "name": "Production Yango Key",
  "apiKey": "cmx_new_key_value_xyz789",
  "platform": "yango",
  "webhookUrl": "https://your-app.com/webhooks/courimax",
  "isActive": true,
  "createdAt": "2026-08-19T10:00:00.000Z",
  "rotatedAt": "2026-08-19T15:00:00.000Z"
}

The old API key is immediately invalidated. Update your systems with the new key.

Revoke API Key

Deactivate an API key.

DELETE /provisioning/organizations/:id/api-keys/:keyId

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID
keyId	string	Yes	API key ID

Headers

Header	Required	Description
X-Provisioning-Secret	Yes	Provisioning secret

Example

curl -X DELETE "https://api.courimax.com/api/provisioning/organizations/org-uuid/api-keys/key-uuid" \
  -H "X-Provisioning-Secret: your_provisioning_secret"

Response (200 OK)

{
  "id": "key-uuid",
  "name": "Production Yango Key",
  "isActive": false,
  "revokedAt": "2026-08-19T15:00:00.000Z"
}

Platform-Specific Keys

Each organization can have one API key per integration platform:

• yango: Yango delivery integration
• galaxis: Galaxis WMS integration
• floating_deli: Floating Deli merchant integration
• standard: General-purpose API access

Attempting to create a second key for the same platform returns a 409 Conflict. Rotate the existing key instead.

Key Security Best Practices

Store Keys Securely

• Use environment variables or secret management
• Never commit keys to version control
• Use different keys for development and production

Rotate Regularly

• Rotate keys periodically (e.g., every 90 days)
• Immediately rotate if a key may be compromised
• Update all systems after rotation

Monitor Usage

• Track lastUsedAt to identify unused keys
• Revoke keys that are no longer needed
• Set up alerts for unusual API usage

Limit Access

• Create separate keys for different services
• Use platform-specific keys when possible
• Implement key rotation in your deployment pipeline

Rate Limiting

API key management endpoints have rate limits:

• GET /api-keys: 120 requests per hour
• POST /api-keys: 60 requests per hour
• POST /api-keys/:keyId/rotate: 60 requests per hour
• DELETE /api-keys/:keyId: 60 requests per hour

Next Steps

• Organizations - Manage tenant organizations
• Authentication - Learn how to use API keys
• Webhooks - Configure webhook notifications