Get the calling key

The calling caller key’s own row and effective scopes, and its own metered usage in three windows (usage). A person key’s fields ride on row. Caller keys only; a session gets 403 caller_key_required. A revoked key gets 403 revoked_key, a paused one 403 key_paused.

Any live caller key (Authorization: Bearer sbc_… or x-api-key: sbc_…).

Operation id getCurrentKey in Keys.

Response 200

The key.

application/json: CurrentKey.

• row CallerKey required
  29 fields

  • id string required
  • user_id string required
  • name string required

    What the tool calls itself, 1-64 chars.

  • mask string required

    The only form shown after mint.

  • created_at string (date-time) required
  • last_used_at string (date-time)
  • revoked_at string (date-time)
  • daily_limit_tokens number

    Daily spend cap in whole credits.

  • monthly_limit_tokens number

    Monthly spend cap in whole credits.

  • caps_unit string

    One of credit.

  • allowed_models array of string

    Glob allow-list over model names; absent = every model. With models_listed: the exact canonical ids the key may dial, and empty = none.

  • models_listed boolean

    true = the listed reading: allowed_models are literal canonical ids (no globs), the key lists exactly those as its per-app picker names, and an empty list allows nothing.

  • model_pins object

    Canonical model id to the stable account id it is pinned to: a pinned model dials only that account, and one id pinned to two accounts gets two picker names.

  • model_aliases object

    Canonical model id (a member of allowed_models) to the custom name its picker shows: 1-64 characters of letters, numbers, dots, dashes or colons; no Cursor routing word (claude, gemini, anthropic, sonnet-, opus-, haiku-, grok, composer); not a house id (superbot, superbot-fast, superbot-omni); unique among this key's forwards; not another model's id. A refused name stores nothing. A custom name replaces the default name for that model.

  • app string

    Forwarding app this listed key's model names are spelled for: cursor, copilot-cli, cline, roo, qwen-code, hermes, openclaw, zazen, default. Set at creation, cannot be changed. Absent = cursor.

  • default_model string

    The model a call that names the bare house agent superbot (the default model of Zapier and n8n), or names no model, is answered by instead: superbot-fast, superbot-omni or a model of one of your own accounts. A call that names any other model is dialled as named. Absent = a call naming superbot gets superbot.

  • route string required

    One of byo, credits, auto.

  • mode string required

    One of model, agent.

  • incognito boolean required
  • device_id string
  • org_id string

    Set on a team key.

  • person_id string

    Set on a key minted for a person: per_ + 16 hex. Every key minted for the same person carries the same id. A person key has no device_id and no org_id, and is billed to the owner.

  • person_name string

    The person's display name, 1-64 characters. Present on every person key.

  • person_email string

    The person's email address, when the owner gave one.

  • person_group string

    A free-text grouping the owner sorts people by (a team, a class), 1-64 characters.

  • prompt_history PromptHistory

    What the owner told a person about their prompts, and how long they are kept. Absent on a key until the owner sets it: the person's prompts are then not visible to the owner and follow the account's own retention.

    3 fields

    • visible_to_owner boolean required

      The owner may read this person's prompts.

    • retention_days integer required

      Whole days the prompts are kept, 1-3650.

    • attested_at string (date-time) required

      ISO 8601 time the owner attested the person was told. The owner's own claim, stored as given and not verified; the answer normalises it to UTC.

  • paused_at string (date-time)

    Set while the owner holds this person: until a PATCH clears it the key answers 403 key_paused at the model gateway, the /v1/keys routes, the relay door and the Cosmos door; every other route does not recognise a held key and answers 401 unauthorized. Held is not revoked. It is written to every live key of the person.

  • person_limit_usd number

    The owner's monthly spend limit for this person, in US dollars to the cent. Set by the owner's PUT /v1/keys/person/{person_id}/limit (the Helper), written to every live key of the person, and absent while no limit is set.

  • scopes array of Scope required

    The EFFECTIVE scopes: stored list or the legacy set, team keys capped. One of gateway:invoke, usage:read, billing:read, keys:read, keys:write, endpoints:read, endpoints:write, teams:read, teams:write, devices:read, devices:write, runs:read, runs:write, mcp:invoke, turns:read.

• scopes array of Scope required

  One of gateway:invoke, usage:read, billing:read, keys:read, keys:write, endpoints:read, endpoints:write, teams:read, teams:write, devices:read, devices:write, runs:read, runs:write, mcp:invoke, turns:read.

• usage KeyUsage required

  This key's own metered usage in three windows: day is the trailing 24 hours (the daily cap's window), week the trailing 7 days, month the current UTC calendar month (the monthly cap's window). Each window reports requests (every metered request), prompts (the requests that were the person's own text), tokens and billed_usd.

  3 fields

  • day KeyUsageWindow required
    5 fields

    • requests integer required

      Distinct metered requests (a request that dialed several times counts once). Every request the key made is one, an agent's tool legs, a title helper and a probe included: the call volume, not what the person asked.

    • prompts integer required

      Distinct answered prompts: requests whose last message was the person's own text and that were answered (the gateway marks the request's row only then), counted once per request id. A tool leg, a title helper, a probe and a refused or failed call are requests but not prompts. Only the dials the gateway wrote a row for are read, so the relay door's turns are not counted here.

    • tokens number required

      Every metered leg: fresh input, output and both cache legs.

    • billed_usd number required

      What the window's calls are worth to the caps and the usage pages, USD: the router's settle once read back, else the metered list value.

    • clients object

      Distinct requests of the window made by Zapier or n8n, counted from the x-superbot-client tag (zapier/<v>, n8n/<v>) the request carried. A platform with no request in the window is absent, and the member is absent when neither made one.

      2 fields

      • zapier integer
      • n8n integer
  • week KeyUsageWindow required
    5 fields

    • requests integer required

      Distinct metered requests (a request that dialed several times counts once). Every request the key made is one, an agent's tool legs, a title helper and a probe included: the call volume, not what the person asked.

    • prompts integer required

      Distinct answered prompts: requests whose last message was the person's own text and that were answered (the gateway marks the request's row only then), counted once per request id. A tool leg, a title helper, a probe and a refused or failed call are requests but not prompts. Only the dials the gateway wrote a row for are read, so the relay door's turns are not counted here.

    • tokens number required

      Every metered leg: fresh input, output and both cache legs.

    • billed_usd number required

      What the window's calls are worth to the caps and the usage pages, USD: the router's settle once read back, else the metered list value.

    • clients object

      Distinct requests of the window made by Zapier or n8n, counted from the x-superbot-client tag (zapier/<v>, n8n/<v>) the request carried. A platform with no request in the window is absent, and the member is absent when neither made one.

      2 fields

      • zapier integer
      • n8n integer
  • month KeyUsageWindow required
    5 fields

    • requests integer required

      Distinct metered requests (a request that dialed several times counts once). Every request the key made is one, an agent's tool legs, a title helper and a probe included: the call volume, not what the person asked.

    • prompts integer required

      Distinct answered prompts: requests whose last message was the person's own text and that were answered (the gateway marks the request's row only then), counted once per request id. A tool leg, a title helper, a probe and a refused or failed call are requests but not prompts. Only the dials the gateway wrote a row for are read, so the relay door's turns are not counted here.

    • tokens number required

      Every metered leg: fresh input, output and both cache legs.

    • billed_usd number required

      What the window's calls are worth to the caps and the usage pages, USD: the router's settle once read back, else the metered list value.

    • clients object

      Distinct requests of the window made by Zapier or n8n, counted from the x-superbot-client tag (zapier/<v>, n8n/<v>) the request carried. A platform with no request in the window is absent, and the member is absent when neither made one.

      2 fields

      • zapier integer
      • n8n integer

Errors