Verify the calling key

The whoami endpoint - returns the calling key’s own object: scopes, status, and effective rate limits. Never any secret material (masked_key only).

Scope: none required. Self-introspection needs no extra scope - the caller is asking about the very key it authenticated with, so requiring a scope to answer “what am I” would be circular. Works with ANY active key, including one with an empty scopes array.

Use it to:

• Prove a key works before wiring it into a system (CI health checks, onboarding flows)
• Debug a 403 - see exactly which scopes the key holds vs what the endpoint needs
• Let integrations self-configure - an agent or app discovers its own permissions and limits at runtime instead of hardcoding them

A key can describe itself but can never enumerate other keys, mint a new key, or revoke any key - all key management (mint, rotate, revoke, edit scopes) is dashboard-only at Settings → Developers → API Keys. This is deliberate: there is no api_keys:manage scope, so a compromised key cannot mint its own replacement or discover sibling keys.

GET /v1/api_keys/me

Verify the calling key

cURL

curl --request GET \
  --url https://api.vexioncards.one/v1/api_keys/me \
  --header 'Authorization: Bearer <token>'

200

{
  "id": "key_8h2K9bP4mR7qX1nF3vT6wY5s",
  "object": "api_key",
  "masked_key": "vxn_sk_8h2K............................wY5sA0jL2dG8",
  "label": "Demo Coffee POS bridge",
  "scopes": [
    "customers:read",
    "customers:write",
    "transactions:write"
  ],
  "inactivity_auto_revoke_enabled": true,
  "status": "active",
  "created_at": 1745832000,
  "last_used_at": 1750691200,
  "rate_limit": {
    "default": "60/min",
    "transactions": "120/min",
    "notifications": "1/min, 50/day"
  }
}

Authorizations

Authorization · string · header · required

Your secret API key as a Bearer token: Authorization: Bearer vxn_sk_.... Keys are created and scoped in the dashboard - see Authentication.

Response

200

application/json

Calling key.

Self-introspection view of the CALLING API key. A key can describe itself but can never enumerate other keys, mint a new key, or revoke any key - minting/rotation/revocation are dashboard-only (Settings → Developers → API Keys). This is the safety rail: a compromised key cannot mint a replacement before being revoked.

id · string · required

Key identifier (key_ prefix). Derived from the key material but NOT usable for authentication.

Pattern: ^key_[A-Za-z0-9]+$

Example:

"key_8h2K9bP4mR7qX1nF3vT6wY5s"

object · string · required

Always "api_key".

Allowed value: "api_key"

masked_key · string · required

Prefix-visible-suffix masked form: first 16 chars visible (vendor prefix + first 9 of suffix), last 12 visible, middle replaced with a dotted run. The plaintext secret is shown exactly once at mint time and never again - lost secret means rotate.

Example:

"vxn_sk_8h2K............................wY5sA0jL2dG8"

label · string · required

Human-readable label set at mint time (e.g. which system uses this key).

Required string length: 1 - 60

Example:

"Demo Coffee POS bridge"

scopes · enum<string>[] · required

Permissions granted to this key, selected at creation time in the dashboard. The v1 scope registry is CLOSED at exactly these NINETEEN scopes; new scopes only ship as part of a versioned API change (see 03-AUTHENTICATION.md). Read does not imply write. Products, custom fields, notification reads and webhook reads each have their own least-privilege scopes. products:read/products:write and custom_fields:read/custom_fields:write replace the earlier cards:read/cards:write borrowing. notifications:read covers the three GET routes (list/retrieve/deliveries); notifications:send still gates the broadcast POST and cancel DELETE. webhooks:read covers read-only webhook surfaces (endpoint list/retrieve/deliveries/event_types, and GET /v1/events); webhooks:manage still gates every mutation, including secret rotation. Self-introspection (GET /v1/api_keys/me) and the shared icon catalog require no scope at all. organization:read was added 2026-07-27 because the invoices list returns real billing data. Keys created earlier were granted the new scopes they need, so no working integration broke.

Available options: customers:read, customers:write, cards:read, cards:write, products:read, products:write, custom_fields:read, custom_fields:write, transactions:read, transactions:write, notifications:send, notifications:read, webhooks:manage, webhooks:read, locations:read, locations:write, team_members:read, team_members:write, organization:read

Example:

[
  "customers:read",
  "customers:write",
  "transactions:write"
]

status · enum<string> · required

Key lifecycle state. Only active keys authenticate. Paused/revoked transitions happen in the dashboard.

Available options: active, paused, revoked

Example:

"active"

created_at · integer · required

Unix seconds at mint time.

Example:

1745832000

inactivity_auto_revoke_enabled · boolean

When true, the key is auto-revoked after 90 days without a request. Default ON.

Example:

true

last_used_at · integer | null

Unix seconds of the most recent authenticated request. Null if never used. Feeds the 90-day inactivity auto-revoke.

Example:

1750691200

rate_limit · object

The effective rate limits for this key, by bucket. Informational - the enforced values.

Show child attributes