Skip to main content
The Teel API uses a secret API key sent as a bearer token on every request. Same pattern as Stripe, OpenAI, Anthropic, Resend. Your server holds the key in env vars or a vault and presents it on every call.

​
Key format

Sandbox provider APIs don’t move real funds — use sk_test_… keys against api-sandbox.teel.finance for end-to-end integration testing before switching to production credentials.
The fixed sk_ prefix is recognized by GitHub secret scanning, GitGuardian, and TruffleHog — if you accidentally commit a key, you’ll get a leak notification. The visible live vs test distinction prevents the “prod creds in Slack” failure mode.
Use each key only against its matching host. A key sent to the wrong environment is rejected with 403 and the body {"error": "environment_scope mismatch"} — sk_live_… belongs on api.teel.finance, sk_test_… on api-sandbox.teel.finance.

​
Issuing a key

API keys are issued by the Teel onboarding team. Email support@teel.finance (or your dedicated onboarding contact) to request:
  • A new sk_test_… sandbox key
  • A new sk_live_… production key (after KYB approval)
  • Additional keys for separate use cases (e.g. one per service)
  • A scope change on an existing key
The plaintext key is delivered through an encrypted channel and shown exactly once — Teel stores only an argon2id hash plus the first 12 characters for identification. We cannot retrieve the plaintext later, so save it to your secret manager immediately. Self-service key creation from the dashboard is on the roadmap.

​
Scopes

Each key carries a subset of scopes. Default for a newly-minted key is read-only: Webhook subscriptions are managed entirely through the API with the webhooks:read / webhooks:write scopes — see the Webhooks guide.

​
Rotation

To roll a key, contact support@teel.finance. We issue a new key alongside the existing one and keep the previous key working for 7 days to give you time to redeploy. After the overlap window, the old key returns 401. Rotations are logged to the partner-visible audit feed under the same business.

​
Revocation

If you suspect compromise, contact support@teel.finance to revoke the key immediately. Active in-memory caches drain within 30 seconds; after that, every request with the revoked key returns 401. Use revocation rather than rotation during incident response — rotation has a 7-day overlap window you don’t want when responding to a leak.

​
What happens if a key is compromised

  1. Blast radius is bounded by the key’s scopes — a key with quotes:read only cannot create payouts. Issue narrowly-scoped keys per use case so a leaked CI key can’t act as a leaked production key.
  2. Teel only custodies funds via escrow + smart wallets. A captured key cannot drain a wallet — it can only place actions the holder of the key could place anyway, all of which are audited and rate-limited.
  3. Revoke first, investigate second. Rotation’s 7-day overlap is wrong for an active compromise; revoke + mint a new key + redeploy.

​
Storage

  • Server-side only. Never embed a sk_live_… key in a mobile app, browser bundle, or any artifact a partner of yours can read. Use a backend you control.
  • One secret per environment. Mirror the key into your env-vars / vault under names like TEEL_API_KEY. Don’t share a key across staging and production.
  • CI secret scanning. Configure your CI to fail on sk_live_ / sk_test_ substrings in commits. Most CI providers have built-in detectors for this prefix shape.

​
Error responses

​
Rate limiting

Per-key rate limits apply. Each response carries:
On a 429, also: Retry-After: <seconds>. Wait at least that long before the next request. Specific limits per endpoint family + the per-key default are documented in the Errors & retries guide.

​
Dashboard authentication

The Teel dashboard is a separate, browser-only session and is not the API authentication path. Partner integrations should always use the sk_ API key pattern above — dashboard sessions are not accepted on api.teel.finance or api-sandbox.teel.finance. If you build an internal tool that needs to act on behalf of multiple Teel accounts, request one sk_ key per account rather than reusing your own dashboard session.