Organization API Keys

Create and manage API keys for B2B partner organizations

Overview

Organization API keys enable B2B partners to access your workspace’s products through their own API credentials. These keys are scoped to specific products and have configurable rate limits.

Create API Key

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

Create a new API key for an organization.

The full API key is only returned once during creation. Store it securely as it cannot be retrieved later.

Request body

scopes · array · default: "[]"

Array of permission scopes for the API key

productIds · array · default: "[]"

Array of product UUIDs the key can access. Empty array means access to all products.

expiresAt · string

ISO 8601 datetime when the key expires. Null for no expiration.

rateLimitPolicy · object

Rate limiting configuration for the key

Show Rate limit properties

rps · integer

Requests per second limit

rpm · integer

Requests per minute limit

burst · integer

Maximum burst size

Request example

curl -X POST "https://api.voyantcloud.com/v1/organizations/org_123/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["products:read", "bookings:write"],
    "productIds": ["prod_abc123", "prod_def456"],
    "expiresAt": "2025-12-31T23:59:59Z",
    "rateLimitPolicy": {
      "rps": 10,
      "rpm": 100
    }
  }'

Response

{
  "data": {
    "id": "orgkey_789xyz",
    "organizationId": "org_123",
    "issuedByWorkspaceId": "wksp_456",
    "key": "org_a1b2c3d4_8kNp2qX4vR9mJ7tY3wL1nC5bD6fG8hK0",
    "keyPrefix": "org_a1b2c3d4",
    "scopes": ["products:read", "bookings:write"],
    "productIds": ["prod_abc123", "prod_def456"],
    "status": "active",
    "expiresAt": "2025-12-31T23:59:59Z",
    "rateLimitPolicy": {
      "rps": 10,
      "rpm": 100
    },
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

List API Keys

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

List all API keys for an organization. Note that the full key value is not returned - only the prefix.

Request example

curl "https://api.voyantcloud.com/v1/organizations/org_123/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "orgkey_789xyz",
      "organizationId": "org_123",
      "issuedByWorkspaceId": "wksp_456",
      "keyPrefix": "org_a1b2c3d4",
      "scopes": ["products:read", "bookings:write"],
      "productIds": ["prod_abc123", "prod_def456"],
      "status": "active",
      "expiresAt": "2025-12-31T23:59:59Z",
      "lastUsedAt": "2024-01-20T14:30:00Z",
      "rateLimitPolicy": {
        "rps": 10,
        "rpm": 100
      },
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Revoke API Key

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

Revoke an organization’s API key. This immediately invalidates the key.

Request example

curl -X DELETE "https://api.voyantcloud.com/v1/organizations/org_123/api-keys/orgkey_789xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "id": "orgkey_789xyz",
    "organizationId": "org_123",
    "status": "revoked",
    "revokedAt": "2024-01-25T16:00:00Z",
    "revokedBy": "system"
  }
}

API Key Format

Organization API keys follow this format:

org_{prefix}_{secret}

• org_ - Fixed prefix identifying this as an organization key
• {prefix} - 8 character identifier (shown in listings)
• {secret} - 32 character cryptographically secure random string

Example: org_a1b2c3d4_8kNp2qX4vR9mJ7tY3wL1nC5bD6fG8hK0

Security Best Practices

• Store API keys in secure environment variables, never in code
• Use the minimum required scopes for each integration
• Set expiration dates for temporary access
• Regularly audit and rotate keys
• Revoke keys immediately when a partner relationship ends