> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryardent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an API key

> Create an API key with a role and optional scopes

<Warning>
  The secret token is shown only once, in the create response. Copy it directly into your secret manager.
</Warning>

The key's role determines what it can do; `scopes` optionally restricts it to a subset of the role's permissions. Scopes are permission keys like `connectors.read` — each role's `permissions` array from [`GET /v1/orgs/{org_id}/roles`](/api/orgs) lists the valid values.


## OpenAPI

````yaml openapi.public.json POST /v1/orgs/{org_id}/api-keys
openapi: 3.1.0
info:
  description: >-
    Public Ardent API. Generated by scripts/export_public_openapi.py — do not
    edit by hand.
  title: Ardent API
  version: v1
servers:
  - url: https://api.tryardent.com
security: []
paths:
  /v1/orgs/{org_id}/api-keys:
    post:
      tags:
        - v1-api-keys
      summary: Create New Api Key
      operationId: create_new_api_key_v1_orgs__org_id__api_keys_post
      parameters:
        - in: path
          name: org_id
          required: true
          schema:
            title: Org Id
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAPIKeyRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKeyCreateResponse'
                additionalProperties: true
                title: Response Create New Api Key V1 Orgs  Org Id  Api Keys Post
                type: object
          description: The created key, including the secret — shown only this once.
        '400':
          description: >-
            Unknown role, non-org role, or a scope outside the role's
            permissions.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - bearerAuth: []
components:
  schemas:
    CreateAPIKeyRequest:
      properties:
        expires_days:
          anyOf:
            - type: integer
            - type: 'null'
          description: Days until expiration (null = never expires)
          title: Expires Days
        name:
          description: Descriptive name for the key
          maxLength: 100
          minLength: 1
          title: Name
          type: string
        role_id:
          description: Role ID to grant to this API key (e.g., role_org_member)
          title: Role Id
          type: string
        scopes:
          default: []
          description: >-
            Permission keys like `connectors.read`, a subset of the role's;
            empty uses all.
          items:
            type: string
          title: Scopes
          type: array
      required:
        - name
        - role_id
      title: CreateAPIKeyRequest
      type: object
    APIKeyCreateResponse:
      additionalProperties: true
      properties:
        api_key:
          description: The full secret key; shown only this once — store it now.
          title: Api Key
          type: string
        api_key_id:
          description: ID of the created key.
          title: Api Key Id
          type: string
        created_at:
          description: When the key was created.
          title: Created At
          type: string
        expires_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When the key expires. Null when it does not expire.
          title: Expires At
        key_prefix:
          description: First characters of the key, for identifying it in lists.
          title: Key Prefix
          type: string
        name:
          description: Human-readable key name.
          title: Name
          type: string
        role_id:
          description: ID of the role granted to the key.
          title: Role Id
          type: string
        role_key:
          description: The role's stable key, for example `role_org_member`.
          title: Role Key
          type: string
        scopes:
          description: Permission scopes granted to the key.
          items:
            type: string
          title: Scopes
          type: array
        warning:
          description: Reminder that the secret cannot be retrieved again.
          title: Warning
          type: string
      required:
        - api_key_id
        - api_key
        - name
        - key_prefix
        - scopes
        - created_at
        - warning
        - role_id
        - role_key
      title: APIKeyCreateResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    bearerAuth:
      description: >-
        Ardent API key (sk-ard_live_… / sk-ard_test_…) or a dashboard session
        token.
      scheme: bearer
      type: http

````