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

# Create an API key

> Creates an API key with the selected permissions. The `secret` is shown exactly once in the response, so store it in a secret manager before you close the dialog or discard the response body.



## OpenAPI

````yaml /api/en/api-keys.yaml post /api/keys
openapi: 3.0.3
info:
  title: Altostrat SDX API Keys API
  version: 1.0.0
  description: >-
    Create, list, inspect, rotate, and revoke SDX API keys through the public
    `/api/keys` gateway path. API key secrets are returned only when you create
    or rotate a key.
servers:
  - url: https://v1.api.altostrat.io
    description: Production API Server
security:
  - BearerAuth: []
tags:
  - name: API Keys
    description: Manage server-to-server credentials for integrations that call SDX APIs.
paths:
  /api/keys:
    post:
      tags:
        - API Keys
      summary: Create an API key
      description: >-
        Creates an API key with the selected permissions. The `secret` is shown
        exactly once in the response, so store it in a secret manager before you
        close the dialog or discard the response body.
      operationId: createApiKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
            example:
              name: Production automation
              permissions:
                - sites:read
                - scripts:write
      responses:
        '201':
          description: The API key was created. Save the returned secret immediately.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeySecretEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    CreateApiKeyRequest:
      type: object
      required:
        - name
        - permissions
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 100
          description: A human-readable key name.
          example: Production automation
        permissions:
          type: array
          minItems: 1
          description: >-
            Permission scopes to grant to the key. You can only grant
            permissions available to your user.
          items:
            type: string
            example: sites:read
    ApiKeySecretEnvelope:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          required:
            - message
            - key
            - secret
          properties:
            message:
              type: string
              example: >-
                API Key created successfully. This is the only time the secret
                key will be shown.
            key:
              $ref: '#/components/schemas/ApiKey'
            secret:
              type: string
              description: The full API key secret. This value is shown only once.
              pattern: ^alto_sk_[0-9A-Za-z]{48}$
              example: alto_sk_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUV
    ApiKey:
      type: object
      required:
        - id
        - object
        - name
        - key_prefix
        - client_id
        - created_at
        - status
      properties:
        id:
          type: string
          pattern: ^api_key_[0-9A-Za-z]{27}$
          example: api_key_2m3h5n7k9j8g7f6e5d4c3b2a
        object:
          type: string
          enum:
            - api_key
          example: api_key
        name:
          type: string
          example: Production automation
        key_prefix:
          type: string
          description: >-
            The visible prefix of the secret. Use this to identify a key without
            exposing its secret.
          example: alto_sk_ab123
        client_id:
          type: string
          description: The backing machine-to-machine client identifier.
          example: C3HqXo4o6Yb5Kp0oV9x8
        permissions:
          type: array
          items:
            type: string
          example:
            - sites:read
            - scripts:write
        created_at:
          type: string
          format: date-time
          example: '2026-04-20T00:00:00Z'
        last_used_at:
          type: string
          format: date-time
          nullable: true
          example: null
        status:
          type: string
          example: active
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          example: The given data was invalid.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
  responses:
    BadRequest:
      description: The request was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: The server could not complete the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Authenticate with an SDX user access token that has permission to manage
        API keys.

````