Email code login

The most common sign-in method is a code from an email. This page describes what happens inside the Fidmos window when a person enters their email: which requests go out, what comes back and what errors can occur.

Note

These requests are made by the window application (loaded via sdk.js), not your backend and not your code on the page. As a partner you do not need to call them directly — you get a single result, an authorization code, in onSuccess (see login widget). This page is here to help you understand the flow and read its errors.

How sign-in goes

1. The person enters their email. The window sends POST /api/v1/embed/login/send with the flow identifier and the address:

   POSThttps://id.fidmos.com/api/v1/embed/login/send

   Content-Type: application/json
   
   { "flow_id": "...", "email": "user@example.com" }

   In response — a send confirmation and timings:

   { "status": "code_sent", "resend_after": 60, "expires_in": 600 }

   resend_after — how many seconds until a resend, expires_in — how long the code lives.

2. The person enters the code. A six-digit code arrives by email (the subject reads “Your sign-in code”). The window verifies it via POST /api/v1/embed/login:

   POSThttps://id.fidmos.com/api/v1/embed/login

   Content-Type: application/json
   
   { "flow_id": "...", "code": "123456" }

   The code is exactly six digits. A successful check returns the flow’s readiness for completion:

   { "status": "authenticated", "completion_handle": "..." }

3. The window completes sign-in and hands your page the authorization code via onSuccess. Next — the usual code-for-token exchange.

Timings and limits

• expires_in — how long the flow lives (and the code inside it). If the flow expired, the check returns flow_expired; if the code is already used or reset — code_expired. In both cases a new code is needed.
• A resend before resend_after does not send a new email. The request returns successfully (code_sent), but the email is not sent again — resend_after tells how many seconds to wait.
• The number of sends is limited (3 by default). Over the limit — code_send_limit.
• The number of entry attempts is limited (5 by default). Once they are exhausted, the window gets code_attempts_exhausted.

Errors of this flow

All error responses come in the envelope { "error": "<code>" }. The code meanings and the general breakdown are in the error reference.

Code	When
invalid_code	the code was entered incorrectly
code_expired	the code has expired
code_attempts_exhausted	entry attempts are exhausted
code_send_limit	the code-send limit is exhausted
flow_too_short	the flow has too little lifetime left — a new code is not issued
invalid_flow_state	the flow is at the wrong step
identity_taken	the method the flow tried to bind is already taken by another user
flow_expired	the flow was not found or has expired
parent_origin_mismatch	the request came from a foreign origin

Tip

Email code is not the only method: a person can sign in through Telegram or with a wallet signature. For you the outcome is the same — an authorization code and, after the exchange, a pairwise sub.