Auth Handoff (Token Exchange)

After magic-link verification the mobile app holds only a short-lived handoff code; this endpoint consumes that code and returns the full set of Cognito tokens so the app can authenticate all future requests.

Flow

1. Client calls handoff endpoint — A POST request is sent with { "code": "<handoff-code>" } immediately after receiving the code from the verify step.

2. Code validation — The Lambda trims the code; an empty string returns HTTP 400 AUTH_HANDOFF_CODE_REQUIRED.

3. Code consumption — consume_handoff_code looks up the code in PostgreSQL. The record is deleted atomically (consumed once). If the code is not found or is expired, None is returned.

4. Response — On success the stored token payload (accessToken, idToken, refreshToken, expiresIn) is returned directly. On failure, HTTP 400 AUTH_HANDOFF_CODE_INVALID is returned.

Entry Point

• Lambda: main/server/api/auth/handoff/app.py → lambda_handler
• HTTP method: POST /auth/handoff (API Gateway)

Dependencies

• PostgreSQL via shared.orm.consume_handoff_code

Error Cases