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

# List BYOK keys

> Lists a workspace's BYOK keys as redacted metadata

Requires `byok:read` scope. Naturally idempotent.

<Note>
  Responses contain redacted metadata only — a masked `key_prefix`, never the provider secret. Submitted secrets can't be retrieved through any endpoint.
</Note>

<Note>
  Items may carry `propagation_status: "pending"` while a change to their provider takes effect (within about 5 minutes).
</Note>

All parameters, request/response schemas, and examples are auto-generated from the [OpenAPI specification](/api-reference/overview).


## OpenAPI

````yaml GET /v1/workspaces/{workspace_id}/byok-keys
openapi: 3.1.0
info:
  title: Auriko API
  version: 1.0.0
  description: >
    Intelligent LLM routing API with OpenAI-compatible interface.


    ## Overview


    Auriko provides a unified API for accessing multiple LLM providers with
    intelligent

    routing based on cost, latency, throughput, and availability.


    ## OpenAI Compatibility


    The API is compatible with OpenAI's Chat Completions API. You can use any

    OpenAI SDK by changing the base URL and API key.


    ## Auriko Extensions


    Beyond OpenAI compatibility, Auriko adds:


    - **Multi-model routing**: Request multiple models with `gateway.models[]`
    array

    - **Routing options**: Control provider selection with `routing` object

    - **Provider extensions**: Pass provider-specific parameters with
    `extensions` object

    - **Routing metadata**: Get transparency into routing decisions via
    `routing_metadata`
  contact:
    name: Auriko Support
    url: https://auriko.ai
  license:
    name: Proprietary
    url: https://auriko.ai/terms
servers:
  - url: https://api.auriko.ai
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Chat
    description: Chat completion endpoints
  - name: Responses
    description: OpenAI Response API endpoints
  - name: Callable Models
    description: Model IDs available for authenticated inference requests
  - name: Model Catalog
    description: Public model and provider catalog endpoints
  - name: Workspaces
    description: Workspace management
  - name: Budgets
    description: Spend control and budget management
  - name: API Keys
    description: API key management
  - name: BYOK
    description: Bring-your-own-key provider key management
  - name: Billing
    description: Credit balance and billing
  - name: Account
    description: API key introspection
  - name: Messages
    description: Anthropic Messages API endpoints
  - name: Routing
    description: Workspace routing configuration
  - name: Usage
    description: Usage statistics and request lookup
  - name: Members
    description: Workspace member and invite management
  - name: Audit
    description: Workspace audit event log
paths:
  /v1/workspaces/{workspace_id}/byok-keys:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace identifier
    get:
      tags:
        - BYOK
      summary: List BYOK keys
      description: |
        Returns the workspace's BYOK keys as redacted metadata (masked key
        prefix only). Provider secrets are never returned by any endpoint.
        Requires `byok:read` scope.
      operationId: listByokKeys
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            type: string
          description: Filter by provider identifier
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListByokKeysResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ListByokKeysResponse:
      type: object
      required:
        - object
        - data
        - count
      properties:
        object:
          type: string
          enum:
            - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/PublicByokKeyItem'
        count:
          type: integer
    PublicByokKeyItem:
      type: object
      description: BYOK key metadata. Redacted — the provider secret is never returned.
      required:
        - id
        - workspace_id
        - provider
        - name
        - key_prefix
        - is_default
        - disabled
        - validation_status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the BYOK key
        workspace_id:
          type: string
          format: uuid
          description: Workspace this key belongs to
        provider:
          type: string
          description: Provider identifier
        name:
          type: string
          description: Human-readable name for the key
        key_prefix:
          type: string
          description: Masked display prefix of the submitted secret
        is_default:
          type: boolean
          description: Whether this key is the provider's default for routing
        disabled:
          type: boolean
          description: >-
            Disabled keys are excluded from routing; the secret stays encrypted
            at rest
        account_tier:
          type:
            - string
            - 'null'
          description: Provider account tier used for rate-limit and data-policy routing
        account_tier_source:
          type:
            - string
            - 'null'
          enum:
            - auto_detected
            - user_specified
            - fallback
            - null
          description: How the tier was determined
        validation_status:
          type: string
          enum:
            - valid
            - pending
            - invalid
            - error
          description: Coarse validation status (no provider diagnostics)
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        last_validated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the key last passed validation (null if never)
        propagation_status:
          type:
            - string
            - 'null'
          enum:
            - pending
            - null
          description: >-
            "pending" while a routing-affecting change for this key's provider
            is committed but edge propagation has not yet been applied
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    ErrorObject:
      type: object
      description: OpenAI-compatible error format
      required:
        - message
        - type
        - param
        - code
      properties:
        message:
          type: string
          description: Human-readable error message
        type:
          type: string
          description: Error category per guide §4.
          enum:
            - invalid_request_error
            - authentication_error
            - permission_error
            - not_found_error
            - rate_limit_error
            - api_error
        param:
          type:
            - string
            - 'null'
          description: Parameter that caused the error (null if not applicable)
        code:
          type: string
          description: Canonical code per guide §5 and docs/reference/error_codes.json.
          enum:
            - invalid_api_key
            - expired_api_key
            - insufficient_permissions
            - feature_disabled
            - mfa_required
            - invalid_recovery_code
            - mfa_verification_failed
            - invalid_request
            - missing_required_parameter
            - invalid_parameter_value
            - payload_too_large
            - context_length_exceeded
            - content_filtered
            - idempotency_conflict
            - idempotency_replay_unavailable
            - field_immutable
            - operation_not_allowed
            - unknown_field
            - state_precondition_failed
            - duplicate_resource
            - method_not_allowed
            - tools_not_supported
            - json_mode_not_supported
            - structured_output_not_supported
            - tools_with_structured_output_not_supported
            - vision_not_supported
            - reasoning_not_supported
            - thinking_disable_not_supported
            - streaming_not_supported
            - non_streaming_not_supported
            - batch_only
            - tier_opt_in_required
            - tool_choice_required_not_supported
            - cost_constraint_exceeded
            - latency_constraint_exceeded
            - throughput_constraint_not_met
            - provider_not_in_allowlist
            - provider_blocked
            - required_params_not_supported
            - byok_keys_required
            - platform_keys_unavailable
            - unsupported_modalities
            - no_compatible_endpoint
            - no_responses_endpoint
            - response_api_only
            - hosted_tool_not_supported
            - model_not_found
            - resource_not_found
            - rate_limit_exceeded
            - budget_exhausted
            - insufficient_quota
            - no_provider_available
            - upstream_error
            - upstream_timeout
            - client_disconnected
            - model_unavailable
            - internal_error
            - service_unavailable
        doc_url:
          type: string
          description: Link to the canonical documentation page for this error code.
        provider:
          type:
            - string
            - 'null'
          description: >-
            Upstream provider that generated the error (e.g.,
            "google_ai_studio", "openai"). Null for errors not attributable to
            an upstream provider (local validation, auth, internal config).
        suggestion:
          type: string
          description: >-
            Actionable fix hint for routing, capability, or model-not-found
            errors. Absent for other error types.
  responses:
    Unauthorized:
      description: Authentication failed
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        X-Error-Type:
          $ref: '#/components/headers/X-Error-Type'
        X-Error-Retryable:
          $ref: '#/components/headers/X-Error-Retryable'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              message: API key is invalid.
              type: authentication_error
              param: null
              code: invalid_api_key
  headers:
    X-Request-ID:
      description: |
        Unique request identifier for debugging and support.
        Include this in support requests for fast resolution.
      schema:
        type: string
      example: req_abc123def456
    X-Error-Type:
      description: |
        Same value as the `error.type` field in the response body, exposed as a
        header for programmatic routing without body parsing.
      schema:
        type: string
        enum:
          - invalid_request_error
          - rate_limit_error
          - api_error
          - authentication_error
          - not_found_error
          - permission_error
      example: invalid_request_error
    X-Error-Retryable:
      description: |
        Whether the client should retry this request.
        'true' for api_error and rate_limit_error types; 'false' for all others.
      schema:
        type: string
        enum:
          - 'true'
          - 'false'
      example: 'false'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: |
        API key authentication.
        Keys start with `ak_` prefix.
        Example: `Authorization: Bearer ak_live_xxxxxxxxxxxx`

````