StatusSign inGet API key
Menu

Agents and accounts

Account, API keys and signup

Use with AI

Sign up, manage API keys (scopes, spend limits, expiry, IP allowlists, live and test modes), read usage and the credit ledger, and get balance alerts.

Everything about your account is an API route, free, and also available in the dashboard.

Sign up

People: create your account on the signup page with Google, GitHub, or an email address and a password (we email you a link to verify the address first). Your first sign-in gives you 100 free credits (once per account, no card) and two keys, a live key and a test key, shown once.

AI agents: an agent without a key signs up with its human's email address:

Shell
curl -X POST https://staging-fly.socialtap.dev/v1/agent_signup \
  -H 'content-type: application/json' \
  -d '{"email": "you@example.com", "name": "my-agent"}'

The answer has two keys. The test key works at once: every endpoint answers from recorded responses, free (see test mode). The live key is pending: it spends nothing and can only call GET /v1/account until the human opens the confirmation email and confirms, which activates it and grants the free credits. Agents never get spending power without a human. Poll GET /v1/account with the live key: api_key.status turns from pending to active. An address that already has an account gets no keys and is not refused: the answer is HTTP 202: The address already has an account: no keys were made; its owner was emailed a sign-in link to create a key for you in the dashboard. Ask them to check their email.

Signup is throttled per IP address and per email address, and disposable email domains are refused.

Routes

RouteWhat it doesAuth
GET /v1/account
Get the account, balance and calling key		The account's balance and plan, the low-balance alert threshold, and the calling key: its mode, scopes, spend limit (with what it used this interval) and expiry. Free; never cached. A pending agent key may call it (and nothing else) to learn when its owner confirmed.key with account:read, or the session
PATCH /v1/account
Update account settings		Sets low_balance_threshold: credits.low (an event and an email to the owner) fires once each time a request takes the balance from above it to at or below it; credits.depleted fires when the balance reaches 0. Free.key with admin, or the session
POST /v1/agent_signup
Sign up as an agent: a test key now, live on confirm		For AI agents: send your human's email address and get a test key that works at once (recorded responses, free) and a live key that stays pending until the human confirms by email, which grants the free credits. Agents never get spending power without a human. For an address that already has an account, no keys are made: the owner is emailed a sign-in link to create one in the dashboard, and the answer is 202 with the human signup's object (check your email).none
POST /v1/api_keys
Create an API key		Creates a key with the given scopes, spend limit, expiry and IP allowlist. The secret is in this answer only: store it now. A key never gets a scope its creator lacks. Free.key with admin, or the session
GET /v1/api_keys/{id}
Get an API key		One key and its spend this interval; never its secret. Free.key with account:read, or the session
GET /v1/api_keys
List API keys		The account's keys, newest first, revoked ones included; never their secrets. Free.key with account:read, or the session
DELETE /v1/api_keys/{id}
Revoke an API key		Revokes a key for good (a key may revoke itself). It stops working within a minute everywhere; revoking it again changes nothing. Free.key with admin, or the session
PATCH /v1/api_keys/{id}
Update an API key		Changes a key's name, scopes, spend limit, expiry or IP allowlist; absent fields keep their value. Takes effect within a minute everywhere. Free.key with admin, or the session
GET /v1/credit_transactions
List credit transactions (the ledger)		Every change to the balance, newest first, cursor-paged: grants (free credits), purchases, hourly usage roll-ups and adjustments. Per-request detail is in GET /v1/usage. Free.key with account:read, or the session
POST /v1/docs_feedback
Send feedback on a docs page		Records whether a docs page helped, with an optional comment: what every docs page's "Was this page helpful?" sends. Agents are welcome to report a page that was wrong, unclear or missing something (set `agent`). Free; limited per IP address.none
GET /v1/security_events
List sign-in and security events		The signed-in person's sign-ins, failed sign-ins, password, email, two-factor and session changes, newest first, with the network and browser each came from. Kept `security_events_retention_s`. Free.dashboard session
POST /v1/session
Start the dashboard: set up the account		The dashboard calls it once it is signed in (people sign in with Google, GitHub or an email address and password on the sign-in page). The first call of a new account returns its live and test keys (secrets shown only here); with agent_token, it approves that agent signup, activating the agent's pending live key and granting the free credits. An account an agent opened that its owner signs in to without approving the agent gets fresh keys, and the agent's are revoked. Free.dashboard session
DELETE /v1/session
Sign out		Ends the session and clears its cookie.dashboard session
GET /v1/session
Get the dashboard session		The signed-in person and account of the session cookie.dashboard session
GET /v1/usage
Usage report: requests and credits over time		Requests, successes, failures, cache hits and credits charged per time bucket, optionally grouped by endpoint, key and outcome. Buckets are listed oldest first, cursor-paged. Data is complete to within about 5 minutes; credits reconcile with the ledger. Free.key with account:read, or the session

API keys

Send the key in the x-api-key header. A key has:

  • a mode: live keys start with st_live_ and make real, billed requests; test keys start with st_test_ and answer from recorded responses, free. The mode is stored with the key; the prefix is only a hint for people.
  • scopes, what it may call. A new key gets every scope but admin unless you choose, and a key never gets a scope its creator lacks. Without the scope a route needs, the answer is forbidden with details.required_scope.
  • an optional spend limit: at most that many credits per UTC day or month. Past it, requests fail with spend_limit_reached (HTTP 402, never retried automatically) until details.resets_at, even when the account still has credits. Concurrent requests can never take a key past its limit.
  • an optional expiry and IP allowlist (addresses or CIDR ranges, IPv4 or IPv6). An expired key, or a call from another address, is refused with forbidden (details.reason says which).

The secret is shown once, when the key is created; the API only ever shows its prefix afterwards. Changes and revocations reach every server within a minute.

ScopeRoutes that need it
endpointsthe routes of its own feature (see above)
jobsPOST /v1/jobs/{id}/cancel, POST /v1/jobs, GET /v1/jobs/{id}, GET /v1/jobs, GET /v1/jobs/{id}/results
account:readGET /v1/account, GET /v1/api_keys/{id}, GET /v1/api_keys, GET /v1/credit_transactions, GET /v1/events/{id}, GET /v1/events, GET /v1/security_events, POST /v1/session, DELETE /v1/session, GET /v1/session, GET /v1/usage, GET /v1/webhook_endpoints/{id}/deliveries, GET /v1/webhook_endpoints/{id}, GET /v1/webhook_endpoints
adminPATCH /v1/account, POST /v1/api_keys, DELETE /v1/api_keys/{id}, PATCH /v1/api_keys/{id}, POST /v1/events/{id}/redeliver, POST /v1/webhook_endpoints, DELETE /v1/webhook_endpoints/{id}, POST /v1/webhook_endpoints/{id}/rotate_secret, POST /v1/webhook_endpoints/{id}/test, PATCH /v1/webhook_endpoints/{id}

Usage and the ledger

GET /v1/usage reports requests, successes, failures, cache hits and credits per hour or day, grouped by endpoint, key or outcome. GET /v1/credit_transactions lists every change to the balance: free credits, purchases, hourly usage and adjustments, with the balance after each.

Balance alerts

Set low_balance_threshold with PATCH /v1/account. When a request takes the balance from above it to at or below it, the account gets a credits.low event and an email to its owner, once per crossing. credits.depleted fires when the balance reaches 0, and api_key.spend_limit_reached the first time in an interval that a key is refused for its spend limit.

The dashboard session

Signing in starts a dashboard session: a signed cookie with the __Host- prefix on this origin (Secure, HttpOnly, SameSite=Lax), checked against the server on every request, so signing out, a password reset or "sign out everywhere else" ends it at once. The session can read and manage the account and keys, never call data endpoints. Every change it makes must come from this origin (the API checks the request's Origin), so another site can neither read nor drive it. Creating or changing API keys needs a recent sign-in: after a while the dashboard asks for your password or a two-factor code again.

Turn on two-factor authentication (an authenticator app, with one-time backup codes) in the security settings: every sign-in then asks for a code, with a password, Google or GitHub alike. The same page lists your sessions and a log of your sign-ins and security changes.

Last updated