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

# Authentication

> API authentication with API keys

# Authentication

All Corbulo API requests require authentication via an API key.

## API Key Authentication

Pass your API key as a Bearer token in the `Authorization` header:

```bash theme={null}
curl "https://app.corbulo.dev/api/v1/projects" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
```

## Creating API Keys

Create API keys from the Corbulo dashboard under **Settings > API Keys**, or programmatically via the API:

<CodeGroup>
  ```bash Create API Key theme={null}
  curl -X POST "https://app.corbulo.dev/api/v1/api-keys" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "CI Pipeline Key",
      "description": "Used in GitHub Actions"
    }'
  ```

  ```json Response theme={null}
  {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "CI Pipeline Key",
    "key_prefix": "ok_live_a1b2",
    "scopes": [],
    "key": "ok_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  }
  ```
</CodeGroup>

<Warning>
  The full API key is only returned once at creation time. Store it securely -- you will not be able to retrieve it again.
</Warning>

## Managing API Keys

### List Keys

```bash theme={null}
curl "https://app.corbulo.dev/api/v1/api-keys" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
```

```json Response theme={null}
{
  "keys": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "CI Pipeline Key",
      "description": "Used in GitHub Actions",
      "key_prefix": "ok_live_a1b2",
      "scopes": [],
      "last_used_at": "2026-03-10T14:30:00Z",
      "created_at": "2026-02-15T09:00:00Z"
    }
  ]
}
```

### Revoke a Key

```bash theme={null}
curl -X DELETE "https://app.corbulo.dev/api/v1/api-keys/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
```

Returns `204 No Content` on success.

## Key Scoping

API keys are scoped to the user who created them. The key inherits the user's project memberships and roles -- it can access the same projects the user belongs to, with the same permissions.

## Error Responses

| Status             | Meaning                                                                      |
| ------------------ | ---------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid API key, or the key has been revoked                      |
| `403 Forbidden`    | The API key's user does not have access to the requested project or resource |

```json 401 Example theme={null}
{
  "error": "unauthorized"
}
```

```json 403 Example theme={null}
{
  "error": "forbidden"
}
```