> ## Documentation Index > Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details. # Create virtual key > Mints a new virtual key and returns the secret exactly once. With `reveal_once` the response withholds the secret and carries `reveal_id` and `preview` instead: the secret is parked for 24 hours and served once, to the person the key is for, through the LangWatch app. scopes defaults to the project the caller names; an API key that names no project must send scopes. Org- and team-scoped keys require virtualKeys:manage at each requested scope. ## OpenAPI ````yaml POST /api/gateway/v1/virtual-keys openapi: 3.1.0 info: title: LangWatch API description: LangWatch openapi spec version: 1.0.0 servers: - url: https://app.langwatch.ai security: - project_api_key: [] paths: /api/gateway/v1/virtual-keys: post: summary: Create virtual key description: >- Mints a new virtual key and returns the secret exactly once. With `reveal_once` the response withholds the secret and carries `reveal_id` and `preview` instead: the secret is parked for 24 hours and served once, to the person the key is for, through the LangWatch app. scopes defaults to the project the caller names; an API key that names no project must send scopes. Org- and team-scoped keys require virtualKeys:manage at each requested scope. operationId: postApiGatewayV1VirtualKeys parameters: - name: Idempotency-Key in: header required: false description: >- A caller-chosen key, 8 to 255 characters, that makes this create safe to retry. The first request to use a key runs normally and its response is stored for 24 hours. A later request with the same key and the same body is not executed again: it returns the stored response, marked with `X-Idempotent-Replay: true`. The same key with a different body is refused 409 `idempotency_error`, as is a retry sent while the original is still running. Only successful responses are stored, so a create that failed can simply be retried with the same key. schema: type: string minLength: 8 maxLength: 255 requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 128 description: type: string principal_user_id: type: - string - 'null' reveal_once: type: boolean scopes: minItems: 1 type: array items: type: object properties: scope_type: type: string enum: - organization - team - project scope_id: type: string minLength: 1 required: - scope_type - scope_id trace_project_id: type: - string - 'null' routing_policy_id: type: - string - 'null' routing_mode: type: string enum: - none - fallback_all - policy expires_at: type: string format: date-time budget: anyOf: - type: object properties: limit_usd: anyOf: - type: number exclusiveMinimum: 0 - type: string pattern: ^\d+(\.\d+)?$ window: type: string enum: - day - week - month on_breach: type: string enum: - block - warn name: type: string minLength: 1 maxLength: 128 required: - limit_usd - window - type: 'null' config: type: object properties: modelsAllowed: default: null anyOf: - type: array items: type: string - type: 'null' providersAllowed: default: null anyOf: - type: array items: type: string - type: 'null' cache: default: mode: respect ttlS: 3600 type: object properties: mode: default: respect type: string enum: - respect - force - disable ttlS: default: 3600 type: integer minimum: 0 maximum: 9007199254740991 fallback: default: maxAttempts: 3 type: object properties: maxAttempts: default: 3 type: integer exclusiveMinimum: 0 maximum: 9007199254740991 guardrailAttachments: default: [] type: array items: type: object properties: direction: type: string enum: - pre - post - stream_chunk guardrailIds: default: [] type: array items: type: string required: - direction rateLimits: default: rpm: null tpm: null rpd: null type: object properties: rpm: default: null anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' tpm: default: null anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' rpd: default: null anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' realtime: default: maxOpenSessions: null type: object properties: maxOpenSessions: default: null anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' metadata: type: object properties: label: type: string tags: default: [] type: array items: type: string external_id: anyOf: - type: string minLength: 1 maxLength: 128 - type: 'null' metadata: type: object propertyNames: type: string minLength: 1 maxLength: 64 additionalProperties: type: string maxLength: 500 purpose: type: string const: user required: - name responses: '201': description: Success content: application/json: schema: type: object properties: virtual_key: type: object properties: id: type: string organization_id: type: string name: type: string description: type: - string - 'null' status: type: string enum: - active - disabled - revoked purpose: type: string enum: - user - langy display_prefix: type: string principal_user_id: type: - string - 'null' trace_project_id: description: >- The project this key's traces and costs land in. Not a scope: it grants no access to the key. Null only on a key created before this was stored. type: - string - 'null' trace_project_archived: type: boolean description: >- True when the project in trace_project_id has been deleted. The key goes on sending its traces there. external_id: type: - string - 'null' metadata: type: object propertyNames: type: string additionalProperties: type: string scopes: type: array items: type: object properties: scope_type: type: string enum: - organization - team - project scope_id: type: string required: - scope_type - scope_id additionalProperties: false routing_policy_id: type: - string - 'null' routing_mode: type: string enum: - none - fallback_all - policy config: {} revision: type: string created_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ updated_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ last_used_at: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ - type: 'null' revoked_at: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ - type: 'null' expires_at: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ - type: 'null' description: >- When the key stops serving, or null for a key that never expires. status stays active past the date on purpose. required: - id - organization_id - name - description - status - purpose - display_prefix - principal_user_id - trace_project_id - trace_project_archived - external_id - metadata - scopes - routing_policy_id - routing_mode - config - revision - created_at - updated_at - last_used_at - revoked_at - expires_at additionalProperties: false secret: description: The secret, absent when `reveal_once` was set. type: string reveal_id: description: >- With `reveal_once`: the id that serves the secret once, through the app. type: string preview: description: >- With `reveal_once`: the key's display prefix, safe to show in place of the secret. type: string required: - virtual_key additionalProperties: false '400': description: Bad Request content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '401': description: Unauthorized content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '403': description: Forbidden content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '409': description: Conflict content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '500': description: Internal Server Error content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable security: - project_api_key: [] components: securitySchemes: project_api_key: type: apiKey in: header name: X-Auth-Token description: >- Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.