Verify Your API Key with _introspect

What _introspect Is For

Before your ERP starts pushing invoices through POST /api/public/v1/invoices/transmit, call _introspect once to confirm that:

• The API key is valid and the bearer token format is correct
• It resolves to the workspace and tenant you expect
• The granted scopes match what your integration needs

This single call lets you fail fast during integration setup instead of debugging cryptic 401 or 403 errors on every endpoint.

Endpoint

GET /api/public/v1/_introspect

Auth: Authorization: Bearer <api_key>

Required scopes: none — any valid API key can introspect itself.

Example

curl -sS https://api.getzutax.com/api/public/v1/_introspect \
  -H "Authorization: Bearer zk_live_<prefix>_<secret>"

Response:

{
  "workspace_id": "8a1c7f6c-61a1-4d89-8d96-3f7e7747f0c0",
  "tenant_id": "f1e2d3c4-b5a6-4789-91a2-b3c4d5e6f7a8",
  "api_key_id": "ak_01HZ7...",
  "scopes": [
    "credit_notes:read",
    "credit_notes:transmit",
    "credit_notes:write",
    "imports:write",
    "invoices:read",
    "invoices:transmit",
    "invoices:write",
    "parties:read",
    "parties:write",
    "payments:write",
    "products:read",
    "products:write"
  ]
}

Failure Modes

| Status | Meaning | Common Cause | |---|---|---| | 401 | Missing or malformed Authorization header | Header is X-API-Key: instead of Authorization: Bearer | | 401 | API key not found, expired, or revoked | Key was rotated; regenerate from the dashboard | | 403 | Key valid but no scopes granted | Key was created without selecting scopes; recreate it |

When to Call _introspect

• At integration setup time — once, after the customer drops in their key, to verify it works.
• After scope changes — when the workspace admin grants additional scopes, _introspect confirms the new scope set is live.
• Not on every request — _introspect is intended for setup and diagnostics, not as a per-request preflight. The public API endpoints already validate scopes; calling _introspect before each real call adds latency without adding safety.

See Also

• Authentication
• Endpoint Reference