---
title: "Create an API key"
method: POST
path: "/api-keys"
tags: ["API Keys"]
---

# Create an API key

`POST /api-keys`

## Request

- Base URL: `https://saturnsql.com/api`
- URL: `https://saturnsql.com/api/api-keys`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Creates a scoped `sat_live_` key. The plaintext `key` is returned ONCE in the response — store it immediately, it cannot be retrieved again. Requires a session token.

## Query parameters

- `name` string, required
- `expiry` string, required
- `scopes` string, required

## Request body

- object
  - `name` string, required: Display name, e.g. the agent it is for
  - `expiry` '24h' | '30d' | '1y' | 'never', required
  - `scopes` string[]: Defaults to ["read"]

## Response `201`

Created (secret shown once)

- object
  - `key` string: The plaintext secret — shown only here.
  - `apiKey` ApiKey: Public shape of an API key (the secret is only returned once, at creation).
    - `id` string
    - `name` string
    - `prefix` string: First chars of the key, for display (e.g. sat_live_ab12cd34).
    - `scopes` string[]
    - `expiresAt` string, date-time, nullable
    - `lastUsedAt` string, date-time, nullable
    - `revokedAt` string, date-time, nullable
    - `createdAt` string, date-time

## Other responses

- `400`: Validation failed
- `401`: Bad or missing credentials

---

[API](https://skmtc.dev/saturnsql/apis/saturnsql-api.md) · [All operations](https://skmtc.dev/saturnsql/apis/saturnsql-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saturnsql/apis/saturnsql-api/revisions/90a3e54ad115?raw)