Auth & Login

Public, unauthenticated endpoints used to sign a driver in: request an SMS verification PIN via /verifications, then exchange phone number + PIN for an access token via /login.

Authentication

Every other request in this collection inherits the collection’s Bearer auth, which sends the accessToken variable in the Authorization header:

Authorization: Bearer &lt;YOUR_ACCESS_TOKEN&gt;

The driver app sends the raw token without Bearer. Both forms are accepted, and the Bearer prefix is case-insensitive.
Tokens are only read from the Authorization header. Query-string tokens are not supported.
Treat the token as an opaque string. Don’t parse it or check its length.

Existing tokens keep working

All existing driver access tokens (UUID format) keep working exactly as they do today. There is no forced migration, and drivers don’t need to sign in again.

Token formats

Format	What it is	Status
`f1rst_s1_<...>`	Driver session token	Rolling out
UUID	Legacy session token	Still issued and supported

> Rolling out: f1rst_s1_ session tokens are being issued gradually, so /login may still return a UUID token for a while. The API already accepts both formats. Handle them the same way.

Sessions

Sign in with Send verification code, then Login (phone + PIN). Save token.id as accessToken and user.id as userId.
Driver endpoints require the runner role. Some also accept admin, but /v3/orders/runner, /offers/runner/:runnerId and /shifts/free/categorized are runner-only.
f1rst_s1_ driver sessions expire after 90 days without use. Legacy UUID tokens don’t expire.
POST /logout with the session’s token revokes that session and returns { "revoked": true }. Any realtime socket using that token is disconnected.
An f1rst_s1_ session stops working when the driver is archived. Archived drivers cannot sign in.
A failed login returns HTTP 200 with { "status": <code>, "message": "<reason>" } in the body.
/login and /verifications allow 5 attempts per minute per phone number and IP, and 20 per minute per IP.

Realtime

The socket authenticate event takes the same token. The server re-checks it every 5 minutes and disconnects the socket once the token is revoked or expired.

Authentication errors

Status	Body	When
`401`	Empty	The token is missing, unknown, expired or revoked
`401`	`Access restricted to: <roles>` (plain text)	The token is valid, but its role cannot call this endpoint
`429`	`Rate limit exceeded` (plain text)	Too many login or verification attempts. Wait for `Retry-After`