---
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`

## Request

- Base URL: `https://api.tryardent.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tryardent.com/v1/orgs/{org_id}/api-keys`
- Auth: none declared

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.dev/tryardent/apis/tryardent-api.md) - [All operations](https://skmtc.dev/tryardent/apis/tryardent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tryardent/apis/tryardent-api/revisions/a0512915b997?raw)