Accounts and keys

#Signing in

There are no passwords. Ask for a sign-in link with your email address; it is valid once, for 15 minutes. The first sign-in creates your account and a personal workspace on the Free plan. Browser sessions last 30 days.

curl -X POST https://api.threefold.eco/api/auth/request-link \
  -H "Content-Type: application/json" -d '{"email": "you@example.com"}'

The endpoint always answers { "ok": true }, so it cannot be used to find out who has an account. It is rate-limited per address and per IP.

#Workspaces

A workspace is the customer: its plan, members, keys, tracked apps, schedules, spend, analyses and reports. The library (charts, listings, ads, posts, reviews, media) is shared by every workspace and collected once: two workspaces tracking the same app in the same market cause one pull, not two. Who tracks an app is not visible to other workspaces.

Members have a role: owner, admin or member. GET /api/me shows your user, role, scopes, plan, usage and workspaces; GET /api/usage shows tracked apps, schedules, spend this month by pillar and analyses against your limits.

#API keys

Create keys in your workspace (POST /api/keys, admin scope) with the scopes they need and an optional expiry. The full key is shown once; threefold stores only its SHA-256 hash and shows a prefix such as tf_live_ab12. Revoke with DELETE /api/keys/:id.

A key can never be created with scopes its creator lacks, and a key created by an expiring key expires no later than it.

#Sandbox keys

Keys that start tf_test_ (POST /api/keys {"name": "CI", "test": true}) read fixture data only, never call a supplier and are never charged. They are read-only: writes and key creation answer 403.

#OAuth 2.1

Chat apps and npx threefold login connect through threefold's OAuth 2.1 authorization server: discovery by RFC 9728 and RFC 8414 metadata, dynamic client registration (RFC 7591), authorization code with PKCE (S256 only), rotating refresh tokens and revocation (RFC 7009). Redirect URIs must match exactly (loopback addresses may use any port). Access tokens last one hour and refresh tokens 30 days; both are stored hashed, and replaying a used authorization code revokes the tokens it issued. A token acts in the workspace and with the scopes you approved on the consent screen. Details: MCP server.

#Keyless access

Without credentials, library reads on /api and /mcp (with ?keyless=1) are allowed up to a daily cap per IP address (50 by default; IPv6 is counted per /64). Responses carry X-Threefold-Next: sign in for the monthly allowance. Past the cap: 429 with Retry-After until the next UTC midnight.

#Rate limits

Each API key and signed-in user has a budget of 120 requests a minute across /api and /mcp by default. Over it: 429 with Retry-After.

#Plans and limits

Plan limits are enforced with 402 and the code plan_limit, with a message that names the limit:

• tracking an app past the plan's app count, target markets per app or pillars;
• live jobs for pillars the plan lacks, or past the workspace's data budget;
• analyses of a kind the plan lacks, past the monthly count, or past the data budget.

Downgrading disables what the new plan no longer covers; nothing is deleted, and upgrading switches it back on. Plans and their limits: Pricing, or GET https://api.threefold.eco/api/billing/plans.

#Enterprise

• Single sign-on (OIDC). Workspaces on the Enterprise plan can sign people in through their own OpenID Connect provider (Okta, Entra ID, Google Workspace and others), with verified domains, just-in-time provisioning and optional enforcement that turns off emailed links for that domain. SAML is not supported yet.
• Audit log. An append-only log of sign-ins, key and token creation and revocation, membership and role changes, plan changes, SSO changes and exports. IP addresses are truncated and user agents stored only as keyed hashes. Read it at GET /api/audit, or export JSON lines.
• History export. One app's listing snapshots, ads and posts as JSON lines, with their stored evidence (GET /api/apps/:id/export).
• Invoicing instead of card payment.
• EU data region. The production deployment runs with the EU region guard on: the API and worker refuse to start if the database or object storage is configured outside the EU. See How it works.