Authentication
Learn how to authenticate your API requests using API Keys.
Authentication Methods
Include your API Key in every request using one of the following methods:
X-API-Key Header
Pass the key directly in the X-API-Key header. This is the recommended method.
curl -H "X-API-Key: amk_your_api_key_here" \ https://your-domain.com/api/v1/ext/orgs/my-org/pods
Authorization Bearer
Alternatively, pass the key as a Bearer token in the Authorization header.
curl -H "Authorization: Bearer amk_your_api_key_here" \ https://your-domain.com/api/v1/ext/orgs/my-org/pods
Scopes
Each API Key is assigned one or more scopes that determine which endpoints it can access. Write scopes implicitly include read access for the same resource.
| Scope | Description | Accessible Endpoints |
|---|---|---|
| pods:read | Read-only access to pods | List pods, get pod details |
| pods:write | Full pod management (includes read) | Create pods, terminate pods + all read endpoints |
| tickets:read | Read-only access to tickets | List tickets, get ticket, get board |
| tickets:write | Full ticket management (includes read) | Create, update, delete tickets + all read endpoints |
| channels:read | Read-only access to channels | List channels, get channel, list messages |
| channels:write | Full channel management (includes read) | Create/update channels, send messages + all read endpoints |
| runners:read | Read-only access to runners | List runners, get runner, list available runners, list runner pods |
| repos:read | Read-only access to repositories | List repositories, get repository, list branches, list merge requests |
Error Handling
The API returns standard HTTP status codes. Common error responses:
| Status Code | Description |
|---|---|
| 400 | Bad Request — Invalid parameters or request body |
| 401 | Unauthorized — Missing or invalid API Key |
| 403 | Forbidden — API Key lacks required scope for this endpoint |
| 404 | Not Found — Resource does not exist or organization slug is invalid |