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

# Create an API Key

> Create a new API key for an organization

Creates an API key. The full key is returned only in this response.

Owners, Admins and Developers can create keys. Viewers can't.

## Request body

<ParamField body="name" type="string" required>
  A name for the key, 3 to 100 characters. Use something that says what the key is for, such as `CI deploy key`.
</ParamField>

<ParamField body="scopes" type="string[]" required>
  At least one scope:

  * `clusters:read`: view services, including their backups, poolers and database users
  * `clusters:write`: create and change services, backups, poolers and database users. Includes read.
  * `clusters:delete`: delete services and backups. Includes read and write.
  * `organizations:read`: view organization details
  * `billing:read`: view billing details and spending caps
  * `billing:write`: manage spending caps. Includes read.
  * `*`: everything your role allows
</ParamField>

<ParamField body="expires_in_days" type="integer">
  Days until the key expires. Leave it out for a key that never expires.
</ParamField>

<ParamField body="organization_id" type="string">
  The organization the key belongs to. Defaults to your current organization.
</ParamField>

## Response

`201 Created`

<ResponseField name="id" type="string">The key's ID.</ResponseField>
<ResponseField name="name" type="string">The key's name.</ResponseField>
<ResponseField name="key" type="string">The full key, starting with `mpg_`. Store it now, because it is never shown again.</ResponseField>
<ResponseField name="key_prefix" type="string">The 8 characters after `mpg_`, used to identify the key.</ResponseField>
<ResponseField name="scopes" type="string[]">The scopes granted to the key.</ResponseField>
<ResponseField name="expires_at" type="string | null">When the key expires, or `null` if it never does.</ResponseField>
<ResponseField name="created_at" type="string">When the key was created.</ResponseField>
<ResponseField name="warning" type="string">A reminder that the key is shown only once.</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.sabaothcloud.com/api/v1/api-keys \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "CI deploy key",
      "scopes": ["clusters:read", "clusters:write"],
      "expires_in_days": 90,
      "organization_id": "YOUR_ORG_ID"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "6f1c2a7e-8a1d-4f53-9b0e-3c1d2e4f5a6b",
    "name": "CI deploy key",
    "key": "mpg_Qw8Rt2Lm9xT4cEa7Hq7Lm2XaPm9xT4cERa41vNq8Zt07kBw3Yd6Uf1Gh5Jk2Np4Sv",
    "key_prefix": "Qw8Rt2Lm",
    "scopes": ["clusters:read", "clusters:write"],
    "expires_at": "2027-01-11T10:00:00Z",
    "created_at": "2026-10-13T10:00:00Z",
    "warning": "Save this key securely! You won't be able to see it again."
  }
  ```

  ```json 403 theme={null}
  {
    "error": "Forbidden",
    "message": "Viewers can't create API keys. Ask an Owner or Admin for a Developer role."
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.