Skip to content

Subscriber sessions

An API key is tenant-wide: a page holding one could read every subscriber’s messages by changing a query parameter. So a browser must not hold it. A subscriber session is a token that authenticates exactly one subscriber’s inbox.

Mint a token

Your backend, after it has authenticated the user, calls:

curl -X POST localhost:3000/v1/subscribers/user-1/session -H "Authorization: ApiKey $KEY"
{ "token": "…", "expiresAt": "2026-10-18T13:00:00Z" }

The response carries Cache-Control: no-store. The subscriber must already exist (404 otherwise), so a token never authenticates a permanently empty inbox. The token is valid for one hour and is stateless: there is no revocation list, so expiry is the only thing that ends it. Mint a new one for a logged-in user as needed.

Use it

curl "localhost:3000/v1/messages" -H "Authorization: Bearer $TOKEN"

The token is accepted only by the four inbox message routes (GET /v1/messages, GET /v1/messages/count, POST /v1/messages/mark, POST /v1/messages/{id}/{action}) and the two phone verification routes, and nowhere else. The restriction is structural, not per-handler: no other route sits behind middleware that accepts a Bearer token.

With a session, the token decides whose inbox it is. A subscriberId in the query or body is replaced by the token’s, never compared, so a client cannot widen its own access by naming someone else. The integrationId listing is refused with 403.

The live stream GET /v1/inbox/stream and everything else under /v1 take an API key only.

Verify a phone

SMS steps text only a phone the subscriber verified, and only the subscriber can verify one: these two routes take a session token and refuse an API key with 403. The token decides whose phone it is; nothing in the body can name another subscriber.

Send a code to a number:

curl -X POST localhost:3000/v1/me/phone/verification -H "Authorization: Bearer $TOKEN" \
  -d '{"phone":"+1 555 123 4567"}'
{ "phone": "+15551234567", "expiresAt": "2026-10-18T12:10:00Z" }

The number is normalised to E.164 (spaces, dots, dashes and parentheses are dropped; it must start with + and a country code). A six-digit code is texted to it through the environment’s primary SMS integration. Then confirm:

curl -X POST localhost:3000/v1/me/phone/verification/confirm -H "Authorization: Bearer $TOKEN" \
  -d '{"code":"123456"}'
{ "phone": "+15551234567", "verifiedAt": "2026-10-18T12:01:12Z" }

The number the code was sent to becomes the subscriber’s verified phone. It replaces any phone they had, including one your backend wrote between the request and the confirm: the subscriber has just proved they hold this number, so it wins. Only the newest code counts, and only once.

Statuserror.codeMeaning
202Code sent (request).
200Phone verified (confirm).
403subscriber_session_requiredCalled with an API key.
422invalid_phoneNot an E.164 number.
429rate_limited5 codes in the last hour for this subscriber, or for this number across subscribers.
429daily_limitThis number has had 10 codes, or 10 wrong guesses across its codes, in the last 24 hours.
429environment_daily_limitThe environment has sent 100 codes in the last 24 hours.
502sms_send_failedThe SMS integration refused or failed the send.
409no_pending_codeNo unused code to confirm.
410code_expiredThe code is more than 10 minutes old. Request a new one.
422wrong_codeThe code does not match.
429too_many_attempts5 wrong codes; this code is spent. Request a new one.

Only a salted hash of each code is stored. Each send is recorded as an sms message on the integration (without the code), so it counts toward the integration’s delivery health like any delivery. A provider error that echoes the number has it replaced by [phone] before it is stored or logged. Deleting a subscriber drops their verification and makes any code they were sent unconfirmable.

The sender API can still write phone on POST and PATCH /v1/subscribers and in a trigger’s to.phone, but that phone is stored unverified, and writing a different number clears a verification. Every phone is stored in E.164, so the same number in another format (+1 (555) 111-2222) is not a change. A phone that cannot be normalised is stored as written, unverified. GET /v1/subscribers/{id} shows phoneVerified.