Skip to content
FlagSwiftDocs

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_session cookie. 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/session returns expiresAt, and the console asks “still here?” before then; POST /api/auth/session/extend is 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 429 carries Retry-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 403 and the code EMAIL_NOT_VERIFIED. Invited members and accounts that existed before verification was added are not affected. See Verify your email.
  • Error replies carry a code next to the message when 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 403 that says the organization is deactivated.

Sign in and out#

Sign in#

POST/api/auth/login

Returns { 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

  • emailstringRequired

    The 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).
  • passwordstringRequired

    Checked 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 Credentials either 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-After seconds.
Request
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"}'
200OK
{
  "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#

POST/api/auth/logout

Clears 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.
Request
curl -s -b jar.txt -X POST https://flags.example.com/api/auth/logout
200OK
{ "status": "success", "message": "Logged out successfully", "data": null }

The current session#

Who am I#

GET/api/auth/session

Returns 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

  • 401Not authenticated: no session, or it was ended.
Request
curl -s -b jar.txt https://flags.example.com/api/auth/session
200OK
{
  "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#

POST/api/auth/session/extend

Gives 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

  • 401Your session has ended. Please sign in again.
  • 403The request came from another origin.
Request
curl -s -b jar.txt -c jar.txt -X POST https://flags.example.com/api/auth/session/extend
200OK
{ "status": "success", "message": "OK", "data": { "expiresAt": 1767229200000 } }

Accounts#

Create an organization#

POST/api/auth/signup

The 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

  • namestringRequired

    Your full name. Trimmed; cannot be blank.
  • orgNamestringRequired

    The organization's name. Trimmed; cannot be blank.
  • emailstringRequired

    Used to sign in. Trimmed and stored in lower case. Not checked for format here. The verification link is sent to this address.
  • passwordstringRequired

    Held 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.
  • 409User 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: false and Resend is available later.
Request
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"}'
200OK
{
  "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#

POST/api/auth/change-password

Ends your other sessions.

Authorization

any signed-in member

Body

  • currentPasswordstringRequired

    Checked before anything changes. Must be sent.
  • newPasswordstringRequired

    Held 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-After seconds.
Request
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"}'
200OK
{ "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#

POST/api/auth/verify-email

A 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

  • tokenstringRequired

    The 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.).
Request
curl -s -c jar.txt -X POST https://flags.example.com/api/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token":"eyJhbGciOi…"}'
200OK
{
  "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#

POST/api/auth/resend-verification

The 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

  • emailstringRequired

    The 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.). Wait Retry-After seconds.
Request
curl -s -X POST https://flags.example.com/api/auth/resend-verification \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@acme.com"}'
200OK
{ "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#

POST/api/auth/forgot-password

The 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

  • emailstringRequired

    The 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.). Wait Retry-After seconds.
Request
curl -s -X POST https://flags.example.com/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email":"dana@example.com"}'
200OK
{ "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#

POST/api/auth/reset-password

Nobody 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

  • tokenstringRequired

    The token from the link in the email (the token query value of the reset page).
  • passwordstringRequired

    Held 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.).
Request
curl -s -X POST https://flags.example.com/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{"token":"eyJhbGciOi…","password":"new-longer-passphrase"}'
200OK
{ "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#

GET/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

  • tokenstringRequired

    The token from the invitation link.

Errors

  • 400Invitation token is required.
  • 404The link is invalid, expired or already used.
Request
curl -s "https://flags.example.com/api/auth/invitation?token=INVITATION_TOKEN"
200OK
{
  "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#

POST/api/auth/invitation

Creates the membership with the invited role, signs the person in and returns { user: { id } }.

Authorization

public

Body

  • tokenstringRequired

    From the invitation link.
  • passwordstringRequired

    For 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.
  • namestring

    Optional; 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.
  • 401Incorrect 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.
  • 409This email already belongs to an organization.
  • 429Too many attempts from this address (checked first).
Request
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"}'
200OK
{ "status": "success", "message": "Welcome aboard", "data": { "user": { "id": "..." } } }

Tokens are shown once

An invitation link is only returned when the invitation is created or reissued. FlagSwift stores a hash, so a lost link is reissued, not recovered.