---
title: "Create New Api Key"
method: POST
path: "/v1/orgs/{org_id}/api-keys"
tags: ["v1-api-keys"]
---

# Create New Api Key

`POST /v1/orgs/{org_id}/api-keys`

Create a new API key for the organization.

Requires 'api_keys.create' permission.

⚠️ IMPORTANT: The secret key is only shown ONCE upon creation.
Store it securely - you won't be able to retrieve it again!

The API key will be granted a role assignment with the specified role_id.
The role determines what permissions the API key has access to.

Common role IDs:
- role_org_viewer: Read-only access
- role_org_member: Create and modify resources
- role_org_admin: Full administrative access (except deleting org)
- role_org_owner: Full control over organization

Args:
    org_id: Organization ID
    body: API key details (name, role_id, scopes, expiration)

Returns:
    API key details INCLUDING the secret key (only time it's shown)

## Path parameters

- `org_id` string, required

## Request body

- CreateAPIKeyRequest — Request body for creating an API key
  - `name` string, required — Descriptive name for the key
  - `role_id` string, required — Role ID to grant to this API key (e.g., role_org_member)
  - `scopes` string[] — Permission keys like `connectors.read`, a subset of the role's; empty uses all.
  - `expires_days` integer, nullable — Days until expiration (null = never expires)

## Response `201`

The created key, including the secret — shown only this once.

- APIKeyCreateResponse — Response of POST /v1/orgs/{org_id}/api-keys. `api_key` is the full secret (sk-ard_live_… / sk-ard_test_…) and is returned only here, once. Spec-only; see APIKeyListItem.
  - `api_key_id` string, required — ID of the created key.
  - `api_key` string, required — The full secret key; shown only this once — store it now.
  - `name` string, required — Human-readable key name.
  - `key_prefix` string, required — First characters of the key, for identifying it in lists.
  - `scopes` string[], required — Permission scopes granted to the key.
  - `expires_at` string, nullable — When the key expires. Null when it does not expire.
  - `created_at` string, required — When the key was created.
  - `warning` string, required — Reminder that the secret cannot be retrieved again.
  - `role_id` string, required — ID of the role granted to the key.
  - `role_key` string, required — The role's stable key, for example `role_org_member`.

## Other responses

- `400` — Unknown role, non-org role, or a scope outside the role's permissions.
- `422` — Validation Error

---

[API](https://skmtc.net/tryardent/apis/fastapi.md) · [All operations](https://skmtc.net/tryardent/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryardent/fastapi/revisions/71b66f68e19c/schema)