STOP WASTING PAID TOKENS. START POOLING ACCOUNTS TODAY. [ GET YOUR VAULT ]

Vault API

The Vault is where your brand's provider API keys live. Keys are encrypted at rest, and every read returns a masked preview rather than the secret. This page documents the key-management surface: listing, adding, editing, testing, and reading spend for a key, plus the public endpoint a contributor uses to hand you a key without exposing it.

Base URL — https://spideriq.ai/api/v1

Authentication

Every endpoint on this page except the public contribution route is brand-scoped and requires one of:

  • a brand_admin or super_admin dashboard session, or

  • a PAT carrying the gate:vault:write scope, whose client belongs to the {brand_id} in the path.

A PAT without that scope receives 403. A PAT belonging to a different brand than the one in the path also receives 403 — a token can only ever act on its own brand.

Authorization: Bearer spideriq_pat_xxxxxxxxxxxx

Key concepts

Three fields decide how a key behaves in the pool, and they are the ones worth understanding before you write anything:

  • cost_type — free, subscription, paid, or unknown. Classified automatically from the provider; you do not set it directly.

  • share_with_pool — whether other brands may draw on this key. Requesting true on a paid key is rejected.

  • billing_mode — auto, subscription, or paid. An owner override for the automatic classification, used when a metered-looking key is actually a flat monthly coding plan.

A paid key can never enter the shared pool. That is enforced three ways: a database trigger coerces the flag, a check constraint backs it up, and the write endpoints reject the attempt with 400 before either fires.

GET /brands/{brand_id}/integrations

Overview of the brand's keys, grouped per provider with summary counts.

Path parameters

  • brand_id (integer, required) — the brand whose vault you are reading.

Example

curl -s "https://spideriq.ai/api/v1/brands/14/integrations" \
  -H "Authorization: Bearer $SPIDERIQ_PAT"

Response — 200. A providers array, each entry carrying the provider name, how many keys it holds, and how many are active and healthy.

Errors:

  • 403 forbidden — the caller is not a member of this brand, or the PAT lacks gate:vault:write. Use a brand_admin/super_admin session, or a PAT for this brand carrying gate:vault:write.

  • 404 not_found — no such brand. Check the id against GET /brands/{brand_id}/integrations/all.

GET /brands/{brand_id}/integrations/all

Every key in the brand's vault, one object per key.

Path parameters

  • brand_id (integer, required).

Example

curl -s "https://spideriq.ai/api/v1/brands/14/integrations/all" \
  -H "Authorization: Bearer $SPIDERIQ_PAT"

Response — 200. Each key includes id, provider_name, key_label, key_preview (first and last four characters only), cost_type, share_with_pool, is_active, health_status, daily_limit, daily_count, minute_limit, minute_count. The secret itself is never returned by any endpoint.

Errors:

  • 403 forbidden — not a member of this brand. Use a brand_admin/super_admin session, or a PAT for this brand carrying gate:vault:write.

  • 404 not_found — no such brand. Check the id against GET /brands/{brand_id}/integrations/all.

GET /brands/{brand_id}/integrations/{integration_id}

A single key.

Path parameters

  • brand_id (integer, required).

  • integration_id (integer, required) — the key's numeric id.

Example

curl -s "https://spideriq.ai/api/v1/brands/14/integrations/42" \
  -H "Authorization: Bearer $SPIDERIQ_PAT"

Response — 200, the same shape as one element of /all, plus the quota and subscription-window fields.

Errors:

  • 403 forbidden — the key belongs to a different brand. Use a brand_admin/super_admin session, or a PAT for this brand carrying gate:vault:write.

  • 404 not_found — no key with that id in this brand. Check the id against GET /brands/{brand_id}/integrations/all.

POST /brands/{brand_id}/integrations

Add a key to the vault. The credentials are encrypted before they are stored.

Body parameters

  • provider_name (string, required, 1–100 chars) — for example openrouter, groq, cerebras, mistral.

  • credentials (object, required) — the provider's credential fields, typically {"api_key": "sk-or-v1-1a2b3c"}.

  • key_label (string, optional, max 255) — a human name for the key.

  • share_with_pool (boolean, optional, default false) — rejected with 400 on a paid provider.

  • daily_limit / minute_limit / hourly_limit (integer, optional) — request ceilings.

  • token_daily_limit / token_monthly_limit (integer, optional) — token ceilings.

  • spend_limit_amount (number, optional) with spend_limit_period (daily | weekly | monthly) and spend_limit_action (warn | block).

  • billing_mode (string, optional) — auto, subscription, or paid.

  • subscription_tier (string, optional) — a curated package key such as codex_pro or minimax_max, which supplies the window size for the capacity meter.

  • priority (integer, optional, 0–100), is_primary (boolean), free_models_only (boolean), supports_embeddings (boolean), contributor_email (string, max 320).

Example

curl -s -X POST "https://spideriq.ai/api/v1/brands/14/integrations" \
  -H "Authorization: Bearer $SPIDERIQ_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_name": "groq",
    "key_label": "Groq - team account",
    "credentials": {"api_key": "gsk_1a2B3c4D5e6F7g8H9i0J"},
    "share_with_pool": true,
    "daily_limit": 14000,
    "minute_limit": 30
  }'

Response — 200, the created key with its key_preview.

Errors:

  • 400 paid_provider_cannot_pool — share_with_pool was true on a paid provider, or on a key whose billing_mode is subscription or paid. The message names the provider. Leave share_with_pool as false. Paid keys stay private to your brand by design.

  • 403 forbidden — not a brand admin, or the PAT lacks gate:vault:write. Use a brand_admin/super_admin session, or a PAT for this brand carrying gate:vault:write.

  • 422 validation_error — a field failed its constraint. Read the detail array; it names the field and the constraint it failed.

  • 502 provider_unreachable — the credential could not be validated against the provider. Retry; if it persists, verify the credential directly with the provider.

PATCH /brands/{brand_id}/integrations/{integration_id}

Edit a key in place. Send only the fields you are changing; omitted fields are untouched.

Body parameters — the same set as create, all optional, plus is_active (boolean) to disable a key without deleting it. credentials may be supplied to rotate the secret.

Example

curl -s -X PATCH "https://spideriq.ai/api/v1/brands/14/integrations/42" \
  -H "Authorization: Bearer $SPIDERIQ_PAT" \
  -H "Content-Type: application/json" \
  -d '{"daily_limit": 20000, "spend_limit_action": "block"}'

Response — 200 with the updated key.

Errors:

  • 400 paid_provider_cannot_pool — an attempt to set share_with_pool on a paid key. Leave share_with_pool as false. Paid keys stay private to your brand by design.

  • 403 forbidden — the key belongs to another brand. Use a brand_admin/super_admin session, or a PAT for this brand carrying gate:vault:write.

  • 404 not_found — no key with that id. Check the id against GET /brands/{brand_id}/integrations/all.

  • 422 validation_error — a field failed its constraint. Read the detail array; it names the field and the constraint it failed.

DELETE /brands/{brand_id}/integrations/{integration_id}

Remove a key from the vault permanently. To take a key out of rotation without losing its history, PATCH is_active to false instead.

Example

curl -s -X DELETE "https://spideriq.ai/api/v1/brands/14/integrations/42" \
  -H "Authorization: Bearer $SPIDERIQ_PAT"

Response — 200 with a confirmation object.

Errors:

  • 403 forbidden — not a brand admin. Use a brand_admin/super_admin session, or a PAT for this brand carrying gate:vault:write.

  • 404 not_found — no key with that id. Check the id against GET /brands/{brand_id}/integrations/all.

POST /brands/{brand_id}/integrations/{integration_id}/test

Send a live probe to the provider using this key and report whether it authenticated.

Example

curl -s -X POST "https://spideriq.ai/api/v1/brands/14/integrations/42/test" \
  -H "Authorization: Bearer $SPIDERIQ_PAT"

Response — 200 with a success flag and the provider's reply summary. A failing probe is still 200; read the flag rather than the status code.

Errors:

  • 403 forbidden — the key belongs to another brand. Use a brand_admin/super_admin session, or a PAT for this brand carrying gate:vault:write.

  • 404 not_found — no key with that id. Check the id against GET /brands/{brand_id}/integrations/all.

  • 502 provider_unreachable — the provider did not answer. Retry; if it persists, verify the credential directly with the provider.

GET /brands/{brand_id}/integrations/{integration_id}/spend

What this key has cost, derived from the gateway request log rather than from the provider's billing API.

Example

curl -s "https://spideriq.ai/api/v1/brands/14/integrations/42/spend" \
  -H "Authorization: Bearer $SPIDERIQ_PAT"

Response — 200 with request counts and cost totals for the key.

Errors:

  • 403 forbidden — the key belongs to another brand. Use a brand_admin/super_admin session, or a PAT for this brand carrying gate:vault:write.

  • 404 not_found — no key with that id. Check the id against GET /brands/{brand_id}/integrations/all.

POST /brands/{brand_id}/integrations/{integration_id}/reauth

Issue a re-authentication link for a key that has stopped working, and email it to the contributor on file. The contributor replaces the secret in place: same key id, same limits, same history.

Body parameters

  • message (string, optional) — a personal note included in the email.

Example

curl -s -X POST "https://spideriq.ai/api/v1/brands/14/integrations/42/reauth" \
  -H "Authorization: Bearer $SPIDERIQ_PAT" \
  -H "Content-Type: application/json" \
  -d '{"message": "Looks like the Groq key expired - could you refresh it?"}'

Response — 200 with the generated link and the address it was sent to.

Errors:

  • 403 forbidden — not a brand admin. Use a brand_admin/super_admin session, or a PAT for this brand carrying gate:vault:write.

  • 404 not_found — no key with that id. Check the id against GET /brands/{brand_id}/integrations/all.

POST /gate/contribute/{token}/api-key

The public endpoint a contributor's browser calls. It takes no authentication: the invite token is the credential, and it expires. This is how a key reaches the vault without the requester ever seeing it.

Path parameters

  • token (string, required) — the invite token from the link.

Body parameters

  • api_key (string, required) — the secret being contributed.

  • provider_name (string, optional) — required only when the invite covers several providers.

Example

curl -s -X POST "https://spideriq.ai/api/v1/gate/contribute/INVITE_TOKEN/api-key" \
  -H "Content-Type: application/json" \
  -d '{"provider_name": "groq", "api_key": "gsk_1a2B3c4D5e6F7g8H9i0J"}'

Response — 200. The key is validated against the provider, encrypted, and stored. The response reports which providers on the invite are still outstanding; the invite flips to completed only when all of them are done.

Errors:

  • 400 invalid_key — the provider rejected the credential. Check the secret was pasted whole, with no leading or trailing whitespace.

  • 404 invite_not_found — unknown or expired token. Ask the requester to send a fresh invite; tokens expire.

  • 429 rate_limited — too many attempts from this token or address. Wait and retry. The public contribution route is limited per token and per address.

Related