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

# Create API key

`POST /api/v1/api-keys`

Create a new API key. The full secret is returned **once** in the `secret` field of the response — store it immediately. Subsequent reads only return the `key_prefix`.

Pass `role_id` to bind the key to an account role; the key inherits that role's permissions. To grant per-project access, after creating the key add it as a [Project Member](#tag/Project-Members/operation/addProjectMember) on each project (passing `api_key_id`).

## Request body

- CreateAPIKeyRequest
  - `name` string, required — A descriptive label for the key (e.g. `Production CI`, `Backups Lambda`)
  - `rate_limit_tier` 'standard' | 'high' — `standard` (30 RPS) by default. `high` (100 RPS) requires support approval — request via email if you need it.
  - `expires_at` string, date-time — Optional expiration timestamp. Omit for never-expires keys.
  - `role_id` string, uuid — Account-level role to assign. The key inherits this role's `account.*` permissions. To grant per-project access, add the key as a Project Member after creation.

## Response `201`

API key created (full secret returned once)

- object
  - `success` boolean
  - `data` APIKeyWithSecret
    - `id` string, uuid, required
    - `account_id` string, uuid
    - `name` string, required
    - `key_prefix` string, required — First 13 characters of the key — the `raff_` prefix plus the first 8 hex characters (e.g. `raff_17d70fcf`). The full secret is only returned once at create or regenerate time.
    - `scope` 'public' — Always `public` for customer-created keys
    - `rate_limit_tier` 'standard' | 'high' — Rate-limit tier. Standard is 30 RPS / burst 60; High is 100 RPS / burst 200.
    - `expires_at` string, date-time — When the key auto-expires. Omitted for never-expires keys.
    - `last_used_at` string, date-time
    - `is_active` boolean, required
    - `role_id` string, uuid — Account-level role this key uses
    - `role_name` string
    - `role_slug` string
    - `project_accesses` APIKeyProjectAccess[] — Per-project access grants
      - `project_id` string, uuid
      - `project_name` string
      - `role_id` string, uuid
      - `role_name` string
      - `role_slug` string
    - `created_by` string, uuid
    - `created_at` string, date-time
    - `secret` string, required — The full API key. **Returned only once** — at create or regenerate time. Store immediately; the secret cannot be retrieved later.

## Other responses

- `400` — Invalid request parameters

---

[API](https://skmtc.net/rafftechnologies/apis/raff-api.md) · [All operations](https://skmtc.net/rafftechnologies/apis/raff-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rafftechnologies/raff-api/versions/a3f123570011/schema)