Skip to content
VectorAxis
API referenceCreate a virtual key
Virtual keys

Create a virtual key

POST/v1/virtual-keys

Create a virtual key.

Creates a key in a workspace and answers its API key (api_key: the slug, a dot, then a secret). The API key is shown only in this response: store it now. Send it as a bearer token in Authorization (or in x-virtual-key) on inference requests. A new key is ACTIVE.

Two credential modes:

  • BYOK (the default): you supply your provider keys in credentials. They are stored encrypted and only their last four characters are ever returned. initial_credits_usd, provider_whitelist and markup_pct are ignored.
  • PLATFORM: requests use VectorAxis's own provider accounts and are paid from your organization's credit balance, at the provider's price plus a markup. initial_credits_usd is required and must be greater than 0; it also becomes the key's credit limit (credit_limit_usd is ignored). credentials are ignored. A PLATFORM key cannot be created while a credit withdrawal is pending.

Every guardrail in guardrail_slugs must exist in the organization and, when the guardrail belongs to a workspace, in the key's workspace.

Requires an organization admin key, or a workspace admin key for workspace_id.

Errors: 400 when a PLATFORM key has no positive initial_credits_usd, provider_whitelist names an unknown provider, or a guardrail slug is unknown, duplicated or in another workspace; 403 without the required role; 409 when the organization already has a key with this name. The organization's subscription must be active and its plan's virtual key quota not yet reached.

Authorization

  • AuthorizationBearer va_

    A platform API key (va_...), created under Settings > API keys. Scoped to an organization or one workspace, with an admin or member role. Used by the management API.

Request body application/json

the key to create

  • namestringrequired

    The key's name, unique within the organization. Required.

  • organizationstringrequired

    The slug of the organization the key belongs to. Required.

  • workspace_idstring<uuid>required

    The workspace the key belongs to (UUID). Required.

  • notestring

    A free-text note about the key. Optional.

  • credential_modeenum<string>

    Where the provider credentials come from: BYOK (your own provider keys, in credentials) or PLATFORM (VectorAxis's provider accounts, paid from your organization's credits). Default BYOK.

    One of "BYOK", "PLATFORM"

  • credentialsobject[]

    Your provider keys, for a BYOK key: one entry per provider. Stored encrypted; only the last four characters of each are ever returned. Ignored for a PLATFORM key.

    Child attributes
    • providerstringrequired

      The provider id, e.g. OPENAI or ANTHROPIC (see "List supported providers"). Required.

    • keystringrequired

      The provider API key. For VERTEX_AI, the Google service-account key file's JSON, as a string. Required.

    • vertex_project_idstring

      For VERTEX_AI: the Google Cloud project id to call. A request's x-vertex-project header overrides it. Ignored for other providers.

    • vertex_regionstring

      For VERTEX_AI: the Vertex AI region (e.g. us-central1, or global). A request's x-vertex-region header overrides it. Ignored for other providers.

  • expires_atstring<date-time>

    When the key expires (ISO 8601 date-time). From then on its requests are refused (403 VIRTUAL_KEY_EXPIRED) and its status becomes EXPIRED, which is final. Absent: the key never expires.

  • metadatamap<string, string>

    Your own string key/value pairs, stored with the key. Optional.

  • model_allowliststring[]

    The models the key may call. A request for any other model is refused (403 MODEL_NOT_ALLOWED). A model matches with or without its provider prefix (openai/gpt-4o matches gpt-4o). Empty or absent: every model.

  • credit_limit_usdnumber<double>

    The most the key may spend, in USD. Once its spend reaches the limit the key becomes EXHAUSTED and its requests are refused (403 VIRTUAL_KEY_EXHAUSTED) until the limit is raised or the spend is reset. Absent: no limit. Ignored for a PLATFORM key, whose limit is initial_credits_usd.

  • credit_alert_threshold_usdnumber<double>

    A soft limit in USD: once the key's spend reaches it, the key carries the ALERT_THRESHOLD_EXCEEDED warning. Requests are not refused. Absent: no alert.

  • credit_reset_policyenum<string>

    When the key's spend goes back to zero: MONTHLY (the 1st of each month, 00:00 UTC), WEEKLY (each Monday, 00:00 UTC) or NEVER. A reset also makes an EXHAUSTED key ACTIVE. Default NEVER.

    One of "MONTHLY", "WEEKLY", "NEVER"

  • rate_limit_rpminteger<int32>

    The most requests the key may make per minute (a 60-second window); over it, 429. Absent: no limit.

  • rate_limit_tpminteger<int32>

    The most tokens the key may use per minute (a 60-second window); over it, 429. Absent: no limit.

  • rate_limit_rpdinteger<int32>

    The most requests the key may make per day (a UTC calendar day); over it, 429. Absent: no limit.

  • initial_credits_usdnumber<double>

    For a PLATFORM key: the credit in USD the key starts with, which is also its credit limit. Required and greater than 0 for a PLATFORM key; ignored for a BYOK key.

  • provider_whiteliststring[]

    For a PLATFORM key: the only providers it may use, as provider ids (e.g. OPENAI, ANTHROPIC). A request for a model of another provider is refused (403 PROVIDER_NOT_WHITELISTED). Empty or absent: any provider VectorAxis serves. Ignored for a BYOK key.

  • guardrail_slugsstring[]

    Slugs of guardrails to run on every request made with this key, in addition to any named in the request's x-guardrail header. Each must belong to the organization and, when it belongs to a workspace, to the key's workspace; no duplicates. Optional.

  • markup_pctnumber<double>

    For a PLATFORM key: the markup on the provider's price as a fraction (0.06 is 6%), replacing the platform's default markup for this key. Absent: the platform default. Ignored for a BYOK key.

Responses

201application/json

Created

  • slugstring

    The key's slug: vk- followed by 16 hex characters. Use it to manage the key.

  • api_keystring

    The API key your applications send: the slug, a dot, then a secret. Send it as a bearer token in Authorization (or in x-virtual-key). Shown only once; only a hash of the secret is kept.

  • token_hintstring

    The last characters of the API key's secret, as later shown on the key as token_hint.

  • key_hintstring

    The last four characters of the first provider credential. An empty string for a PLATFORM key.

NVIDIA Inception Program member

VectorAxis is built by GK Labs, a member of NVIDIA Inception.

© 2025 NVIDIA, the NVIDIA logo, and NVIDIA Inception are trademarks and/or registered trademarks of NVIDIA Corporation in the U.S. and other countries.