Guides

Authentication and environments

API keys, the sandbox and live environments, and what each key can see.

API keys#

Authenticate every request with a secret API key in the Authorization header:

Shell

curl "https://sdk.tilt-pay.com/v1/me" \
  -H "Authorization: Bearer $TILT_PAY_API_KEY"

Keys are created in the Hub, per project and per environment (Developers, then Create key):

Environment	Key format	Use
Sandbox	`tp_test_` + 32 characters	Development and tests. Simulated wallets, KYC and transactions. No money moves.
Live	`tp_live_` + 32 characters	Production. Requires live access to be enabled for your organization.

The environment is carried by the key, not by the URL: both use the same host and the same routes. A tp_test_ key always targets the sandbox (simulator); a tp_live_ key always targets production. Live keys are refused with 403 live_not_enabled until your organization's business verification (KYB) is approved (see Going live).

Warning API keys are secrets. Keep them on your server, in a secrets manager or environment variables. Never ship a key in a mobile app, a web page or a public repository. The Hub shows the full secret only once, at creation; afterwards you only see the prefix and the last four characters. If a key leaks, revoke it in the Hub and create a new one: revocation takes effect immediately.

What a key can see#

A key only sees the data of its project and its environment:

A user created with a sandbox key is invisible to a live key of the same project (404), and the other way around.
A resource that belongs to another project looks exactly like a resource that does not exist (404). The API never answers 403 for another project's data.

Authentication errors#

Case	Status	`error.code`
`Authorization` header missing, or the scheme is not `Bearer`	401	`missing_api_key`
Unknown or malformed key	401	`invalid_api_key`
Revoked key	401	`api_key_revoked`
Your organization has been suspended	403	`organization_suspended`
Live key while live access is not enabled	403	`live_not_enabled`
A `/v1/sandbox/*` route called with a live key	403	`sandbox_only`

All errors share one format, described in Errors.

Sandbox and live#

Authentication, rate limits, idempotency, errors, pagination, the key introspection route, fees and the event log behave identically in both environments. What differs is the data behind them:

Feature	Sandbox	Live
Users	Real rows, phone number considered verified (`verified: true`)	Real rows, `verified: false` until you verify the phone number
Wallets	Simulated address, no real operation	Created right after the user (`wallet_status`: `ready`, or `pending` while it is created or retried), when live wallets are enabled for your project. `balance_usdc` is the real balance only when balance reading is enabled, and `null` otherwise
Phone verification	No message sent, the code is always `123456`	Real one-time codes (WhatsApp, then SMS), when enabled: `403 live_feature_unavailable` otherwise
KYC	Simulated with the simulator; the session is simulated too	Read-only reflection of the real status; real sessions when enabled (`409 feature_unavailable` otherwise)
Transactions	Simulated, no money moves	The user's real transactions in your project
Events	Emitted by the simulator and by the user routes	`user.` events are emitted by the API; `kyc.`, `transaction.` and `withdrawal.` events only once Tilt Pay has activated them for the platform

Several live features are switched on by Tilt Pay, per platform, and are off by default. Until they are switched on, live behaves as the right-hand column says. The go-live checklist explains how to find out what is active for you.

Note Tilt Pay never holds your users' funds, and no route of this API moves money.

Check which key you are using#

Introspect the API key returns the environment, the project, your plan, whether live access is enabled and the key's own prefix and last four characters (never its secret).