Authentication

Trile has three authentication modes because three different actors talk to it. As an integrating developer you’ll almost always use the first one.

1. API keys (your server → Trile)

The public /v1 integration API authenticates with a secret API key sent in the x-api-key header:

curl "$TRILE_API/v1/customers" -H "x-api-key: nep_live_..."

Prefix	Environment	Moves real money?
nep_test_	Sandbox / test mode	No
nep_live_	Production	Yes

• Keys are created in the merchant dashboard or via POST /v1/merchant/api-keys.
• The raw secret is shown only once, at creation. Trile stores only a SHA-256 hash.
• An API key is bound to one business and one environment (stored server-side — it can’t be switched by tampering with metadata).
• Rotate with POST /v1/merchant/api-keys/:keyId/rotate (issues a new secret, lets you retire the old one).

Keep secret keys secret

Never ship a nep_live_ (or nep_test_) key in browser, mobile, or other client-side code. Treat it like a password. If one leaks, rotate it immediately.

2. End-user sessions (phone + OTP)

Your customers authenticate to wallet and checkout endpoints with a phone number and a one-time code — not an API key. The flow:

1. POST /v1/auth/start with a phone number → Trile sends a 6-digit OTP (valid 5 minutes).
2. POST /v1/auth/verify with the code → Trile returns a session (cookie + bearer token) and creates the user + wallet on first login.

OTP sends are rate-limited (1 per 60s, 5 per hour per phone). You normally never build this yourself — hosted checkout handles the customer’s OTP flow for you.

3. Merchant dashboard (email + password + TOTP)

The merchant dashboard (managing your business, keys, branding, team) uses email + password with optional TOTP two-factor, via Better Auth sessions. These are the /v1/merchant/*, /v1/security/*, and team endpoints. They authenticate with a session cookie, not an API key.

Which mode does an endpoint use?

Endpoint group	Auth
/v1/customers, /v1/catalog/*, /v1/subscriptions, /v1/invoices, /v1/events, /v1/webhooks/*, /v1/checkout/sessions (create)	API key (or merchant session)
/v1/wallet/*	End-user session (phone OTP)
/v1/checkout/sessions/:token/* (the hosted flow)	Anonymous + a per-session bearer
/v1/merchant/*, /v1/security/*, /v1/merchant/team/*	Merchant session

The API Reference marks the security scheme on every operation.

Request requirements recap

Every authenticated write also needs an Idempotency-Key. A minimal authenticated POST therefore carries three headers:

x-api-key: nep_live_...
Idempotency-Key: 7f9c2a1e-...
Content-Type: application/json