Users and verification

A user is one person on your platform. They verify their email once with a 6-digit code. Flume then links them to a Flume account and gives you a user access token.

How do you identify a user?

You send external_ref: your own permanent id for the person.

• Keep it stable. Flume uses it to find the user's earlier searches and quotes.
• Never reuse it for another person.
• 1 to 128 characters.

How does verification work from your own screens?

1. Call POST /users/trigger-verification with external_ref and email. Flume emails the code.
2. Show a code box. masked_email tells the user which inbox to check.
3. Call POST /users/confirm-verification with email and code.
4. Store access_token from the response. It is returned once.

Step by step with code: Verify a user.

How does verification work in the iframe?

The first open: the user verifies, you get a token. Happens once per user. You build no screen for it: the iframe asks for the code.

Read this diagram as text

1. The iframe opened without a user access token, so it shows the user their name and email. The user clicks Connect.
2. The iframe asks Flume to email a code.
3. Flume emails a 6-digit code to the user. It is valid for 10 minutes.
4. The user types the code in the iframe.
5. The iframe checks the code with Flume. Any token you held for this user stops working now.
6. The iframe posts flume:user_connected with a connect code.
7. Your page sends the connect code to your backend, at once.
8. Your backend calls POST /users/exchange-connect-code. The code works once, within 120 seconds.
9. Flume returns the user access token, once.
10. Your backend checks external_ref, then stores the token over any older one. It sends it on the next POST /start-iframe-session.

1. You call POST /start-iframe-session without a user access token.
2. The iframe asks the user to verify, and checks the code itself.
3. Your page receives flume:user_connected with a connect_code.
4. Your backend calls POST /users/exchange-connect-code within 120 seconds.
5. Your backend checks external_ref in the response, then stores access_token.
6. Next time, send the token on POST /start-iframe-session. The iframe opens with the user already verified.

A later open, for a user whose token you hold. No email step and no flume:user_connected. Lighter steps happen only when the stored token has stopped working.

Read this diagram as text

1. The user clicks your button for one item.
2. Your page asks your backend to start a session.
3. Your backend calls POST /start-iframe-session and sends the user access token it stored for this user.
4. Only when the token no longer works, because the user verified again or you revoked it: Flume answers 401 USER_TOKEN_INVALID.
5. Then your backend deletes the stored token.
6. Then your backend calls POST /start-iframe-session again without a token. The user verifies in the iframe, as on a first open.
7. Flume returns iframe_url and session_uuid.
8. Your backend returns those two values to your page.
9. Your page starts the ready timer, adds the message listener and sets the iframe src.
10. The iframe spends the launch code with Flume.
11. The iframe posts flume:iframe_ready and opens with the user already verified.

What happens when a user verifies in the iframe?

A user has one working access token at a time. Each verification issues a new one and stops the one before.

Moment	Effect on tokens
The user confirms the code in the iframe	Any token you hold for this user stops working. The iframe's own session keeps working
Your backend exchanges the connect code	Flume issues the user's new token and returns it to you
You never exchange the connect code	You hold no working token for this user

What this means for your backend:

• Always exchange the connect code, at once, and overwrite the stored token.
• Always send the token you hold on POST /start-iframe-session. The iframe then opens verified, and no new token is issued.
• If you use both the API and the iframe, expect API calls to return 401 USER_TOKEN_INVALID between the user's verification in the iframe and your exchange. Retry them with the new token.
• Another iframe that was open for the same user ends at its next call. It posts flume:close_iframe with reason expired.

What are the rules for a code?

Rule	Value
Length	6 digits
Valid for	10 minutes
Wrong tries before it is burned	3
Wait before a resend	30 seconds
Codes per mailbox	5 in 24 hours
Codes per user IP address, when you send X-Flume-Client-IP	30 in 1 hour
Codes per partner	500 per UTC day

• A resend replaces the earlier code.
• X-Flume-Client-IP is optional. When you send the user's IP address, Flume also limits codes per IP address. Without it, only the limits per mailbox and per partner apply.

What happens to the user's Flume account?

account in the response tells you.

Value	Meaning
CREATED	Flume opened a new Flume account with the details you sent
LINKED	The email already had a Flume account. Flume linked it and wrote nothing to it

Searches, quotes and projects you create for the user appear in that account.

How long does a user access token last?

It has no expiry date. It stops working when one of these happens.

Event	Result
You call DELETE /users/{external_ref}/token	The token stops at once. Iframe sessions opened with it end at their next call
The user confirms a code again, on your screens	The response holds a new token. The old one stops
The user verifies in the iframe	The old token stops. The new one comes from the connect code exchange
You call trigger-verification with a new email for a known external_ref	The user verifies the new address. The old token stops

A stopped token returns 401 USER_TOKEN_INVALID. Verify the user again to get a new one.

How do you update a user's details?

Call POST /users/trigger-verification again with the same external_ref.

• A field you leave out is kept.
• A field you send as null is cleared.
• The call also sends a fresh code.

What can go wrong?

Situation	Status	Code
Wrong code	422	VERIFICATION_CODE_INVALID. The message says how many tries are left
Third wrong code	422	VERIFICATION_TRIES_EXHAUSTED. Send a new code
Code expired, used or never sent	422	VERIFICATION_CODE_EXPIRED. Send a new code
Resend too soon, or a mailbox or IP limit	429	VERIFICATION_RATE_LIMITED. Wait Retry-After seconds
The email could not be sent	502	VERIFICATION_EMAIL_FAILED. Retry
The email belongs to a closed Flume account	422	USER_ACCOUNT_CLOSED. On every other call this code is a 403
No user of yours with that email awaits a code	404	NOT_FOUND

Every code is in the error catalog.