> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyantcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

### Request body

<ParamField body="scopes" type="array" default="[]">
  Array of permission scopes for the API key
</ParamField>

<ParamField body="productIds" type="array" default="[]">
  Array of product UUIDs the key can access. Empty array means access to all products.
</ParamField>

<ParamField body="expiresAt" type="string">
  ISO 8601 datetime when the key expires. Null for no expiration.
</ParamField>

<ParamField body="rateLimitPolicy" type="object">
  Rate limiting configuration for the key

  <Expandable title="Rate limit properties">
    <ParamField body="rps" type="integer">
      Requests per second limit
    </ParamField>

    <ParamField body="rpm" type="integer">
      Requests per minute limit
    </ParamField>

    <ParamField body="burst" type="integer">
      Maximum burst size
    </ParamField>
  </Expandable>
</ParamField>

### Request example

```bash theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
curl "https://api.voyantcloud.com/v1/organizations/org_123/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json theme={null}
{
  "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

```bash theme={null}
curl -X DELETE "https://api.voyantcloud.com/v1/organizations/org_123/api-keys/orgkey_789xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json theme={null}
{
  "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

<Tip>
  * 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
</Tip>