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

# Create user API key

`POST /api/v1/user-api-keys`

## Request

- Base URL: `https://app.scanopy.net`
- URL: `https://app.scanopy.net/api/v1/user-api-keys`
- Auth: API key in cookie `session_id`

## Request body

- UserApiKey
  - `expires_at` string, date-time, nullable: When this record stops being valid.
  - `is_enabled` boolean: Whether the key may still be used. Disabled keys are rejected.
  - `key` string, required: The stored key. Returned redacted except on creation and rotation.
  - `last_used` string, date-time, nullable, required: When this key was last used to authenticate.
  - `name` string, required: Human-facing name for this key.
  - `organization_id` string, uuid, required: The organization that owns this record.
  - `permissions` 'Owner' | 'Admin' | 'Member' | 'Viewer'
  - `site_ids` string[]: Site IDs this key has access to (hydrated from junction table)
  - `tags` string[], required: Tags assigned to this entity.
  - `user_id` string, uuid, required: User the key acts on behalf of.
  - `created_at` string, date-time, required: When this record was first created.
  - `id` string, uuid, required: Server-assigned unique identifier.
  - `updated_at` string, date-time, required: When this record was last modified.

## Response `200`

API key created

- ApiResponseUserApiKeyResponse: Envelope for a successful response. Failures are sent with a non-2xx status and an `ApiErrorResponse` body instead.
  - `data` object: Response for user API key creation/rotation Contains the full API key record plus the plaintext key (shown only once)
    - `api_key` UserApiKey, required
      - `expires_at` string, date-time, nullable: When this record stops being valid.
      - `is_enabled` boolean: Whether the key may still be used. Disabled keys are rejected.
      - `key` string, required: The stored key. Returned redacted except on creation and rotation.
      - `last_used` string, date-time, nullable, required: When this key was last used to authenticate.
      - `name` string, required: Human-facing name for this key.
      - `organization_id` string, uuid, required: The organization that owns this record.
      - `permissions` 'Owner' | 'Admin' | 'Member' | 'Viewer'
      - `site_ids` string[]: Site IDs this key has access to (hydrated from junction table)
      - `tags` string[], required: Tags assigned to this entity.
      - `user_id` string, uuid, required: User the key acts on behalf of.
      - `created_at` string, date-time, required: When this record was first created.
      - `id` string, uuid, required: Server-assigned unique identifier.
      - `updated_at` string, date-time, required: When this record was last modified.
    - `key` string, password, required: The plaintext API key - only returned once during creation or rotation
  - `error` string, nullable: Not sent on a successful response. Failure messages arrive in an `ApiErrorResponse`.
  - `meta` ApiMeta, required: API metadata included in all responses
    - `api_version` integer, required: API version (integer, increments on breaking changes)
    - `server_version` string, required: Server version (semver)
  - `success` boolean, required: Always `true` on a successful response.

## Other responses

- `400`: Bad request
- `403`: Invalid permissions or site access
- `500`: Internal server error

## Changes

- **2026-10-26** `c9d9d46d1ae8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/scanopy/apis/scanopy-api/changes/api/v1/user-api-keys/post.md)

---

[API](https://skmtc.dev/scanopy/apis/scanopy-api.md) - [All operations](https://skmtc.dev/scanopy/apis/scanopy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scanopy/apis/scanopy-api/revisions/966ba786bdb5?raw)