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

# Add a virtual key

> Mint a virtual key scoped to models, with a budget, rate limits, and expiry.



## OpenAPI

````yaml openapi.yaml POST /key/generate
openapi: 3.1.0
info:
  title: ForceAI Gateway API
  version: 1.0.0
  description: >
    Core ForceAI Gateway operations: add a model, mint a virtual key, register
    an A2A agent, and run a chat completion. The gateway is OpenAI compatible,
    so any OpenAI SDK works by pointing base_url at it. Management operations
    (add model, add key, add agent) are admin actions on the control plane; chat
    completions run on the gateway data plane.
servers:
  - url: https://gateway.your-domain.com
    description: >-
      ForceAI endpoint (gateway for chat completions; control plane for admin
      operations)
security:
  - bearerAuth: []
tags:
  - name: Chat
    description: OpenAI-compatible inference
  - name: Models
    description: Add and manage models (admin)
  - name: Keys
    description: Mint and scope virtual keys (admin)
  - name: Agents
    description: Register A2A agents (admin)
paths:
  /key/generate:
    post:
      tags:
        - Keys
      summary: Add a virtual key
      description: >
        Mint a virtual key scoped to models, with a budget, rate limits, and
        expiry. Hand it to a consumer; they call the gateway with it. Scope
        `models` to a single Smart Router for the simplest safe public setup.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateKeyRequest'
            example:
              key_alias: acme-corp
              models:
                - smart-router
              max_budget: 25
              budget_duration: 30d
              rpm_limit: 120
              tpm_limit: 200000
              duration: 90d
      responses:
        '200':
          description: The generated key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateKeyResponse'
              example:
                key: sk-5AKAW_A...
                key_alias: acme-corp
                models:
                  - smart-router
                max_budget: 25
                rpm_limit: 120
                expires: '2026-10-06T14:44:35Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    GenerateKeyRequest:
      type: object
      properties:
        key_alias:
          type: string
        models:
          type: array
          items:
            type: string
          description: Allow-list of models this key may call.
        max_budget:
          type: number
        budget_duration:
          type: string
          example: 30d
        rpm_limit:
          type: integer
        tpm_limit:
          type: integer
        duration:
          type: string
          description: Key lifetime.
          example: 90d
    GenerateKeyResponse:
      type: object
      properties:
        key:
          type: string
        key_alias:
          type: string
        models:
          type: array
          items:
            type: string
        max_budget:
          type: number
        rpm_limit:
          type: integer
        expires:
          type: string
          format: date-time
  responses:
    Unauthorized:
      description: Missing or invalid key
      content:
        application/json:
          example:
            error:
              message: Authentication Error, No api key passed in.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A ForceAI virtual key or the master key, sent as `Authorization: Bearer
        <key>`.

````