Authentication
Create an account, verify its email, sign in, check who you are, extend or end a session, and accept an invitation.
How sessions work#
- Signing in sets the
auth_sessioncookie. It is a signed token tied to a session version, so signing in again or changing your password ends every older session at once. - A session lasts 60 minutes. Each person has one session at a time: signing in (with a password, an invitation or a verification link) ends any session on another device, and if two sign-ins race the last one wins. The signed-out device is sent to the sign-in page with a notice. API keys and SDK traffic do not use sessions and are not affected.
GET /api/auth/sessionreturnsexpiresAt, and the console asks “still here?” before then;POST /api/auth/session/extendis that confirmation.- Sign-in and sign-up are rate limited per address (and, for sign-in, per address and email), and changing a password limits wrong guesses per member. A
429carriesRetry-After. The limits are listed under Rate limiting. - An account created through sign-up cannot sign in until its email address is verified: the sign-in is refused with a
403and the codeEMAIL_NOT_VERIFIED. Invited members and accounts that existed before verification was added are not affected. See Verify your email. - Error replies carry a
codenext to themessagewhen the server has one, for example{ "status": "error", "message": "…", "code": "EMAIL_NOT_VERIFIED" }. Match on the code, not the message. - Members of a deactivated organization cannot sign in unless they are the owner; the reply is a
403that says the organization is deactivated.
Sign in and out#
Sign in#
/api/auth/loginReturns { user } and sets the session cookie. Signing in ends any session you had on another device. The invited email with the one-time password from an invitation also signs in and accepts that invitation. A wrong email or password is a 401 with the same message either way.
The EMAIL_NOT_VERIFIED refusal is only given after the password has been confirmed, so a wrong password never learns whether an account exists or is unverified. No session is started, the refusal does not count as a failed attempt, and a new verification email is sent (within the verification email limits).
Authorization
public
Body
emailstringRequiredThe member's email address. Surrounding spaces and case are ignored for rate limiting only; send it as it was registered (sign-up stores it in lower case).passwordstringRequiredChecked against the account. Signing in only asks for 6 characters, so passwords made under an older rule still work; the password rule applies when a password is created.
Errors
- 400Invalid JSON (
Invalid JSON body), or email or password is not a string (Invalid Credentials). - 401Wrong email or password:
Invalid Credentialseither way. - 403The email is not verified yet (
EMAIL_NOT_VERIFIED:Verify your email to sign in. We sent a link to the address.); your organization is deactivated and you are not its owner (ORG_DEACTIVATED); or the request came from another origin. - 429Too many failed attempts (by default 10 per address and email, or 50 per address, in 15 minutes). Wait
Retry-Afterseconds.
curl -s -c jar.txt -X POST https://flags.example.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","password":"your-password"}'{
"status": "success",
"message": "Login successful",
"data": {
"user": { "id": "...", "name": "Ada Lovelace", "email": "you@example.com", "organizationId": "...", "isOwner": true }
}
}
# Set-Cookie: auth_session=...; HttpOnly; SameSite=Lax; Path=/Sign out#
/api/auth/logoutClears this browser's cookie. Because only one session exists per person, signing out here ends it.
Authorization
public
Errors
- 403The request came from another origin.
curl -s -b jar.txt -X POST https://flags.example.com/api/auth/logout{ "status": "success", "message": "Logged out successfully", "data": null }The current session#
Who am I#
/api/auth/sessionReturns id, name, email, organizationId, role, roleName and customRoleId (set for custom roles, otherwise null), productionWrite (whether the role may change production targeting), isOwner, organizationDeactivated, expiresAt (milliseconds since the epoch) and the full list of permissions the role holds. Use it to decide what to offer; the server still checks every call.
Authorization
signed in
Errors
- 401
Not authenticated: no session, or it was ended.
curl -s -b jar.txt https://flags.example.com/api/auth/session{
"status": "success",
"message": "OK",
"data": {
"expiresAt": 1767225600000,
"id": "...",
"name": "Ada Lovelace",
"email": "you@example.com",
"organizationId": "...",
"role": "organization_admin",
"roleName": null,
"customRoleId": null,
"productionWrite": true,
"isOwner": true,
"organizationDeactivated": false,
"permissions": ["flags.read", "flags.update", "..."]
}
}Extend the session#
/api/auth/session/extendGives the same session a fresh period without signing anyone out elsewhere. An expired or revoked session cannot be extended and gets a 401.
Authorization
signed in
Errors
- 401
Your session has ended. Please sign in again. - 403The request came from another origin.
curl -s -b jar.txt -c jar.txt -X POST https://flags.example.com/api/auth/session/extend{ "status": "success", "message": "OK", "data": { "expiresAt": 1767229200000 } }Accounts#
Create an organization#
/api/auth/signupThe person who signs up becomes the organization's owner, but is not signed in: the account is created unverified and a link is emailed to the address. Opening it (see Verify your email) verifies the address, sends the welcome email and signs the person in. The call needs an email provider and APP_URL on the server to send the link; without them the reply has emailed: false and the account cannot be finished.
An address that already has a verified account is a 409. An address whose earlier sign-up was never verified is not an error: the earlier attempt is replaced by this one (new password, name and organization name), a new link is sent and the reply is the same as for a new account. Links sent before the replacement stop working, so whoever controls the mailbox finishes the sign-up with the credentials they chose last.
This endpoint takes no confirmation field. The console's sign-up form asks you to repeat the password in Confirm password, but that is checked in the browser only and is never sent.
Authorization
public
Body
namestringRequiredYour full name. Trimmed; cannot be blank.orgNamestringRequiredThe organization's name. Trimmed; cannot be blank.emailstringRequiredUsed to sign in. Trimmed and stored in lower case. Not checked for format here. The verification link is sent to this address.passwordstringRequiredHeld to the fixed password rule: at least 6 characters including a number, a symbol, and both upper and lower case letters, at most 72 bytes, and not equal to your email. The reply lists exactly what is missing, for example Include a number. Include a symbol.
Errors
- 400Invalid JSON; a field is not a string (
Invalid input) or is blank (All fields are required); or the password breaks the rule (the message lists what to fix). - 403The request came from another origin.
- 409
User already exists. - 429Too many accounts created from this address (5 an hour by default). Checked before the body is read. Verification emails over their own limit are not an error: the reply says
emailed: falseand Resend is available later.
curl -s -X POST https://flags.example.com/api/auth/signup \
-H "Content-Type: application/json" \
-d '{"name":"Ada Lovelace","orgName":"Acme","email":"ada@acme.com","password":"a-long-passphrase"}'{
"status": "success",
"message": "Check your email to finish signing up",
"data": { "verificationRequired": true, "email": "ada@acme.com", "emailed": true }
}
# No Set-Cookie: nobody is signed in until the emailed link is opened.
# When the email could not be sent: "emailed": false, plus "emailError" with the reason (not set when email is not configured).Change password#
/api/auth/change-passwordEnds your other sessions.
Authorization
any signed-in member
Body
currentPasswordstringRequiredChecked before anything changes. Must be sent.newPasswordstringRequiredHeld to the password rule (see sign-up), must differ from the current password and may not equal your email.
Errors
- 400Invalid JSON or a missing field (
Current password is required,Password is required); the current password is wrong (Current password is incorrect); the new one equals it; or the new one breaks the password rule. - 401No session.
- 403You have no organization or role, the organization is deactivated, or the request came from another origin.
- 429Five wrong current passwords in 15 minutes. Wait
Retry-Afterseconds.
curl -s -b jar.txt -c jar.txt -X POST https://flags.example.com/api/auth/change-password \
-H "Content-Type: application/json" \
-d '{"currentPassword":"old-passphrase","newPassword":"new-longer-passphrase"}'{ "status": "success", "message": "Password changed. Any other session was signed out.", "data": null }Verify your email#
Signing up checks that the person owns the mailbox before they are signed in. The link in the verification email works for 24 hours and opens the console's /verify-email page, which calls the endpoint below. This confirms the email address only: FlagSwift does not verify anyone's identity (there is no KYC check). Invited members prove their mailbox by opening their invitation link and are never asked again.
Verify the email address#
/api/auth/verify-emailA valid link marks the address verified, sends the welcome email and starts the person's session in the same way signing in does, so it ends any session they had elsewhere. Opening the same link again answers alreadyVerified with no session.
Authorization
public
Body
tokenstringRequiredThe token from the link in the verification email (the token query value of the verify page).
Errors
- 400Invalid JSON or no token; the link is not valid, was replaced by a newer sign-up, or belongs to no account (
INVALID_TOKEN); or it is older than 24 hours (TOKEN_EXPIRED). Request a new link. - 403The request came from another origin.
- 429Ten submissions from one network address in 15 minutes (
Too many attempts. Try again later.).
curl -s -c jar.txt -X POST https://flags.example.com/api/auth/verify-email \
-H "Content-Type: application/json" \
-d '{"token":"eyJhbGciOi…"}'{
"status": "success",
"message": "Email verified",
"data": { "user": { "id": "...", "name": "Ada Lovelace", "email": "ada@acme.com", "organizationId": "...", "isOwner": true } }
}
# Set-Cookie: auth_session=...; HttpOnly; SameSite=Lax; Path=/
# A link for an account that is already verified signs nobody in:
{ "status": "success", "message": "This email is already verified. Sign in to continue.", "data": { "alreadyVerified": true } }Send a new verification link#
/api/auth/resend-verificationThe answer is the same whether or not the address has an account, so the call cannot be used to find out who is registered. A link is only sent when the address has an account that is still unverified. Earlier links keep working until they expire, unless a newer sign-up replaced the password.
Authorization
public
Body
emailstringRequiredThe address that signed up.
Errors
- 400Invalid JSON or not an email address.
- 403The request came from another origin.
- 429Five requests an hour for the same email from one network address, or twenty an hour from one network address (
Too many verification emails requested. Try again later.). WaitRetry-Afterseconds.
curl -s -X POST https://flags.example.com/api/auth/resend-verification \
-H "Content-Type: application/json" \
-d '{"email":"ada@acme.com"}'{ "status": "success", "message": "If that address has an account waiting to be verified, a new link is on its way. It expires in 24 hours.", "data": null }Forgot and reset password#
Two public calls for someone who cannot sign in. The first emails a one-time link; the second sets the new password from it. The link works once and expires after 30 minutes, and resetting ends every session the account has. It needs APP_URL and an email provider on the server.
Request a reset link#
/api/auth/forgot-passwordThe answer is the same whether or not the address has an account, so the call cannot be used to find out who is registered.
Authorization
public
Body
emailstringRequiredThe address the account signs in with.
Errors
- 400Invalid JSON or not an email address.
- 403The request came from another origin.
- 429Three requests an hour for the same email from one network address, or twenty an hour from one network address (
Too many reset requests. Try again later.). WaitRetry-Afterseconds.
curl -s -X POST https://flags.example.com/api/auth/forgot-password \
-H "Content-Type: application/json" \
-d '{"email":"dana@example.com"}'{ "status": "success", "message": "If that address has an account, a reset link is on its way. It works once and expires soon.", "data": null }Reset the password#
/api/auth/reset-passwordNobody is signed in by this call. The person signs in with the new password, and a notice is emailed to the account.
Authorization
public
Body
tokenstringRequiredThe token from the link in the email (the token query value of the reset page).passwordstringRequiredHeld to the password rule (see sign-up) and different from the current password.
Errors
- 400The link expired or was already used (
INVALID_RESET_TOKEN), or the password breaks the policy. - 403The request came from another origin.
- 429Ten reset-link submissions from one network address in 15 minutes (
Too many attempts. Try again later.).
curl -s -X POST https://flags.example.com/api/auth/reset-password \
-H "Content-Type: application/json" \
-d '{"token":"eyJhbGciOi…","password":"new-longer-passphrase"}'{ "status": "success", "message": "Password updated. Sign in with your new password.", "data": null }Accepting an invitation#
These two calls are for the person who received an invitation link, so they need no session. Creating invitations is on the Members page.
Preview an invitation#
/api/auth/invitation?token=…Shows who invited the visitor, to which organization and role, for a valid, unexpired link. Not cached.
Authorization
public
Query parameters
tokenstringRequiredThe token from the invitation link.
Errors
- 400
Invitation token is required. - 404The link is invalid, expired or already used.
curl -s "https://flags.example.com/api/auth/invitation?token=INVITATION_TOKEN"{
"status": "success",
"message": "OK",
"data": {
"email": "sam@acme.com",
"name": "Sam",
"role": "developer",
"roleLabel": "Developer",
"organizationName": "Acme",
"invitedByEmail": "ada@acme.com",
"expiresAt": "2026-10-10T09:00:00.000Z",
"hasAccount": false
}
}Accept an invitation#
/api/auth/invitationCreates the membership with the invited role, signs the person in and returns { user: { id } }.
Authorization
public
Body
tokenstringRequiredFrom the invitation link.passwordstringRequiredFor a new person, the password for the new account, held to the password rule (see sign-up). If the invited email already has an account that belongs to no organization, send that account's current password instead.namestringOptional; defaults to the name they were invited under. Up to 80 characters. Ignored when the account already exists.
Errors
- 400Invalid JSON, a missing field (
Invitation token is required,Password is required), a name over 80 characters, or a new account's password that breaks the password rule. - 401
Incorrect password: the email already has an account and the password does not match it. - 403The request came from another origin.
- 404The link is invalid, expired or already used.
- 409
This email already belongs to an organization. - 429Too many attempts from this address (checked first).
curl -s -c jar.txt -X POST https://flags.example.com/api/auth/invitation \
-H "Content-Type: application/json" \
-d '{"token":"INVITATION_TOKEN","password":"a-long-passphrase","name":"Sam"}'{ "status": "success", "message": "Welcome aboard", "data": { "user": { "id": "..." } } }Tokens are shown once