Authentication
People sign in with their Stellar wallet. Agents use a token that the operator issues. Both send Authorization: Bearer <token>. There are no API keys for third parties.
Wallet sign-in (people)
POST /v1/auth/challengewith{ "address": "G..." }returns{ challenge, expiresAt }.- The wallet signs the challenge text with SEP-53: ed25519 over
sha256("Stellar Signed Message:\n" + challenge). Freighter'ssignMessagedoes this. POST /v1/auth/verifywith{ address, challenge, signature }(base64 or hex) returns{ session: { token, address, expiresAt } }.- Send the token on every call:
Authorization: Bearer <token>.
Challenge format
Stellar-Split sign-in
Address: G...
Nonce: <id>.<expiry ms>.<hmac>
Expires: 2026-10-26T08:05:00.000Z
The API checks that the text is exactly the one it issued for that address, that it has not expired, that the signature verifies against the address, and then burns the nonce. A second verify with the same challenge fails with 401 UNAUTHORIZED.
Sessions
| Property | Value |
|---|---|
| Challenge lifetime | 5 minutes, single use |
| Session lifetime | 12 hours (expiresAt in the verify response) |
| Format | HMAC-SHA256 signed with the server SESSION_SECRET. Stateless, so it works across serverless instances |
| Renewal | None. Sign in again when it expires |
| Logout | Drop the token on the client. There is no server-side revoke for human sessions |
The web app keeps the token in localStorage until it expires, and removes it on disconnect or account change.
Agent tokens
An agent authenticates with a random token issued by the operator. The API stores only its SHA-256, mapped to the agent's Stellar address, in the AGENT_TOKENS environment variable (sha256hex=GADDRESS pairs, comma separated).
TOKEN=$(openssl rand -base64 32)
printf %s "$TOKEN" | sha256sum # the hash goes into AGENT_TOKENS on the API
# the token itself goes only into that agent's MCP server environment
- An agent token has no expiry. Revoke it by removing its hash from
AGENT_TOKENSand redeploying. - Agent routes for linking (
/v1/agents/link*,/v1/me/agents) answer403 FORBIDDENto an agent: only a signed-in person can manage links. - Agents are capped per payment, per 24 hours and per 30 days. See spend policy.
Headers
| Header | Use |
|---|---|
Authorization: Bearer <token> | Every route except GET /v1/health, POST /v1/auth/challenge and POST /v1/auth/verify |
Content-Type: application/json | POST and PATCH bodies. Bodies must be a JSON object |
Idempotency-Key | Optional on POST /v1/groups/:id/expenses. 8 to 64 letters, digits, - or _ |
PAYMENT-SIGNATURE | Only on the x402-style intent route, see the API reference |
Keep secrets off the client
Any request body that contains something shaped like a Stellar secret key (S plus 55 base32 characters) is refused with 400 SECRET_KEY_REJECTED, before parsing and again after, so JSON escapes do not get past it. Sign in the wallet, send only signatures and public addresses.
- Keep agent tokens and
MCP_AUTH_TOKENon servers. Never ship them in a browser bundle or a mobile app. - Session tokens are bearer credentials. Send them only over HTTPS to the API origin.
- The Supabase service role key lives only in the API. The browser gets no database credential.