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

# API Keys — create and rotate authentication keys

> Create, list, rotate, and revoke API keys programmatically or through the dashboard. Manage publishable and secret keys across test and live environments.

API keys authenticate every request to the Borga API. Each key has a `type` of either `publishable` (safe to expose in client-side code) or `secret` (server-side only), and a `mode` of either `test` or `live`. You can manage keys here or through the dashboard.

<Warning>
  A rotated or revoked key cannot be recovered. Update your integrations with the new key immediately after rotating, as the old key is invalidated at the moment of rotation.
</Warning>

***

## List API keys

`GET /v1/api_keys`

Returns a list of all API keys for your merchant account.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.borga.is/v1/api_keys \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

<ResponseField name="data" type="object[]" required>
  Array of API key objects.

  <Expandable title="key fields">
    <ResponseField name="id" type="string" required>
      Unique key identifier.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Key type. One of `publishable` or `secret`.
    </ResponseField>

    <ResponseField name="mode" type="string" required>
      Key mode. One of `test` or `live`.
    </ResponseField>

    <ResponseField name="label" type="string">
      Optional label for identifying the key.
    </ResponseField>

    <ResponseField name="last4" type="string" required>
      Last four characters of the key value. The full key is only shown once at creation or rotation.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 timestamp of when the key was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "key_01hx9z3k2mfq7nbvd4cw8ej5rt",
        "type": "secret",
        "mode": "live",
        "label": "Production server",
        "last4": "x9kZ",
        "created_at": "2026-04-29T10:15:00Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## Create an API key

`POST /v1/api_keys`

Creates a new API key. The full key value is returned only in this response — store it securely before continuing.

### Request parameters

<ParamField body="type" type="string" required>
  Key type. One of `publishable` or `secret`.
</ParamField>

<ParamField body="mode" type="string" required>
  Key mode. One of `test` or `live`.
</ParamField>

<ParamField body="label" type="string">
  Optional label to help identify the key's purpose (e.g. `"Production server"`, `"Mobile app"`).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.borga.is/v1/api_keys \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx" \
    --header "Content-Type: application/json" \
    --data '{
      "type": "secret",
      "mode": "live",
      "label": "Production server"
    }'
  ```
</RequestExample>

### Response fields

<ResponseField name="id" type="string" required>
  Unique key identifier.
</ResponseField>

<ResponseField name="type" type="string" required>
  Key type: `publishable` or `secret`.
</ResponseField>

<ResponseField name="mode" type="string" required>
  Key mode: `test` or `live`.
</ResponseField>

<ResponseField name="label" type="string">
  Key label.
</ResponseField>

<ResponseField name="key" type="string" required>
  The full key value. This is the only time it is returned in plaintext — save it now.
</ResponseField>

<ResponseField name="last4" type="string" required>
  Last four characters of the key value.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the key was created.
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "key_01hx9z3k2mfq7nbvd4cw8ej5rt",
    "type": "secret",
    "mode": "live",
    "label": "Production server",
    "key": "sk_live_...",
    "last4": "x9kZ",
    "created_at": "2026-04-29T10:15:00Z"
  }
  ```
</ResponseExample>

***

## Rotate an API key

`POST /v1/api_keys/{id}/rotate`

Generates a new value for an existing key and immediately invalidates the old one. Use this to rotate credentials without deleting and re-creating the key object.

<Warning>
  The old key is invalidated immediately. Update every integration using this key before rotating.
</Warning>

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the key to rotate.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.borga.is/v1/api_keys/key_01hx9z3k2mfq7nbvd4cw8ej5rt/rotate \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

Returns the updated key object with the new `key` value in plaintext. After this response, the new value is only available via `last4`.

<ResponseField name="id" type="string" required>
  Unique key identifier.
</ResponseField>

<ResponseField name="type" type="string" required>
  Key type.
</ResponseField>

<ResponseField name="mode" type="string" required>
  Key mode.
</ResponseField>

<ResponseField name="label" type="string">
  Key label.
</ResponseField>

<ResponseField name="key" type="string" required>
  The new full key value. Save this now — it will not be shown again.
</ResponseField>

<ResponseField name="last4" type="string" required>
  Last four characters of the new key value.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of the original key creation.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "key_01hx9z3k2mfq7nbvd4cw8ej5rt",
    "type": "secret",
    "mode": "live",
    "label": "Production server",
    "key": "sk_live_...",
    "last4": "m3Pq",
    "created_at": "2026-04-29T10:15:00Z"
  }
  ```
</ResponseExample>

***

## Revoke an API key

`DELETE /v1/api_keys/{id}`

Permanently revokes an API key. Any requests using this key will be rejected immediately.

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the key to revoke.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.borga.is/v1/api_keys/key_01hx9z3k2mfq7nbvd4cw8ej5rt \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

Returns an empty body with a `204 No Content` status on success.

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>