Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.recoupable.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Every request to the Recoup API must be authenticated using exactly one of two mechanisms:
MethodHeaderUse case
API Keyx-api-keyServer-to-server integrations
Access TokenAuthorization: Bearer <token>Frontend apps authenticated via Privy
Providing both headers in the same request will result in a 401 error.
Agent onboarding endpoints (POST /api/agents/signup and POST /api/agents/verify) are unauthenticated — they exist so agents can obtain their first API key. See the Agents guide for details.

​
API Keys

API keys are the primary way to authenticate programmatic access to the Recoup API. All API keys are personal keys — they are always tied to the account that created them.

​
Creating an API Key

  1. Navigate to chat.recoupable.com/keys
  2. Enter a descriptive name (e.g. "Production Server")
  3. Click Create API Key
Copy your API key immediately — it is only shown once. Keys are stored as a secure HMAC-SHA256 hash and cannot be retrieved after creation.

​
Using an API Key

Pass your key in the x-api-key header: 
curl -X GET "https://api.recoupable.com/api/tasks" \
  -H "x-api-key: YOUR_API_KEY"

​
Access to Organizations

If your account belongs to one or more organizations, your API key can access data across those organizations by passing an account_id parameter on supported endpoints. This lets you filter to any account within an organization your key has access to.
  • No org membership — the key can only access its own account’s data
  • Org member — the key can pass account_id to filter to any account within that organization
Org membership is determined by the account’s organizations. An account gains access to an org when it is added as a member.

​
Access Tokens (Privy)

If you’re building a frontend application that authenticates users via Privy, you can pass the user’s Privy JWT as a Bearer token instead of an API key. 
curl -X GET "https://api.recoupable.com/api/tasks" \
  -H "Authorization: Bearer YOUR_PRIVY_JWT"
The API validates the token against Privy, extracts the user’s email, and resolves it to the corresponding Recoup account. Bearer tokens always authenticate as a personal account — they cannot act on behalf of an organization.

​
How We Verify Access on API Calls

Every authenticated request goes through validateAuthContext, which enforces the following access rules:

​
API Key or Bearer Token

By default, requests access the key owner’s own account. When account_id is provided: 
Request includes account_id override?
  ├── Same as key owner → Allowed (self-access)
  ├── Key owner is a member of an org that contains account_id → Allowed
  └── No matching org membership → 403 Forbidden
Membership is verified by checking the key owner’s organizations for a record linking the account to the target account’s organization.
The Recoup internal admin organization has universal access to all accounts.

​
Organization Access via organization_id

Some endpoints accept an organization_id parameter. When provided, the API additionally validates that the authenticated account is either:
  • A member of the organization, or
  • The organization account itself

​
Error Responses

StatusCause
401Missing or invalid credentials, or both x-api-key and Authorization headers provided
403Valid credentials but insufficient access to the requested account_id or organization_id

​
Security Notes

  • API keys are never stored in plaintext — only an HMAC-SHA256 hash (keyed with your project secret) is persisted in the database
  • Never include account_id in your API key creation request — the account is always derived from your authenticated credentials
  • Rotate keys immediately if compromised via the API Keys Management Page