POST/auth/login

Sign in

Exchanges an email address and password for an access token, or reports that two-factor verification is still required before a token is issued.

AccessNo sign-in required

A successful sign-in returns the access token that every authenticated endpoint expects as Authorization: Bearer <access-token>. It also sets a secure refresh cookie through Set-Cookie, which POST /auth/refresh later uses to issue a fresh access token without asking for the password again. Keep the returned sid, since refreshing needs it.

Read requires_2FA before you use anything else in the response. When it is false, as in the sample, token is your access token and token_2fa is unused. When it is true, token is empty and the sign-in is not finished: take the token_2fa value and the one-time code sent to the account's email address and complete the sign-in with POST /auth/otp-validate. The user_info object is the User shape described in Shared objects, and it carries the organisations, workspaces, and role the account can work in.

An empty token is not a failure

A response with "success": true and an empty "token" means two-factor verification is outstanding, not that the call went wrong. Branch on requires_2FA rather than on whether a token is present.

Body parameters

emailstringrequired

The address the account was registered with.

passwordstringrequired

The account's password.

locationstringoptional

Where the sign-in is being made from, if your client can determine it.

devicestringoptional

The device the sign-in is being made from, if your client can determine it.

bash

curl -X POST "$SQRL_API/auth/login" \
  -H "content-type: application/json" \
  -c sqrl-cookies.txt \
  -d '{
        "email": "operator@example.com",
        "password": "<account-password>",
        "location": "London, GB",
        "device": "treasury-ops-cli"
      }'

const res = await fetch(`${process.env.SQRL_API}/auth/login`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  credentials: "include",
  body: JSON.stringify({
    email: "operator@example.com",
    password: "<account-password>",
    location: "London, GB",
    device: "treasury-ops-cli",
  }),
});
const { requires_2FA, token, token_2fa, sid, user_info } = await res.json();

rust

let res = client
    .post(format!("{}/auth/login", api_base))
    .json(&serde_json::json!({
        "email": "operator@example.com",
        "password": "<account-password>",
        "location": "London, GB",
        "device": "treasury-ops-cli",
    }))
    .send()
    .await?;

Response200 OK

{
"success": true,
"requires_2FA": false,
"token_2fa": "",
"token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MDIxIn0.7Qk1x…f3d",
"sid": "sid_01HZXD5N8V",
"user_info": {
  "UUID": 4021,
  "Email": "operator@example.com",
  "FirstName": { "String": "Ada", "Valid": true },
  "Surname": { "String": "Okafor", "Valid": true },
  "LastLogin": { "Time": "2026-08-03T09:14:22Z", "Valid": true },
  "PhoneNumber": { "String": "+441632960431", "Valid": true },
  "DefaultOrg": 118,
  "DefaultWorkspace": 342,
  "OrganisationsInfo": {
    "Organisations": [
      {
        "OrgID": 118,
        "OrgName": "Northgate Treasury",
        "Workspaces": {
          "Workspaces": [
            {
              "WorkspaceInfo": {
                "uid": 342,
                "name": "Treasury Operations",
                "description": "Live issuance and settlement",
                "net": "mainnet"
              },
              "Role": {
                "RoleId": 77,
                "Name": "Approver",
                "Description": "Reviews and signs pending movements",
                "Perm": [
                  { "UID": 6, "RuleName": "PAYMENT_APPROVE" },
                  { "UID": 8, "RuleName": "VIEW_BALANCES" }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}
}

#What happens next

With requires_2FA false, send token as a bearer token on every later call and refresh it with POST /auth/refresh before it expires. With requires_2FA true, the platform emails a one-time code to the account and waits: nothing is signed in until POST /auth/otp-validate accepts that code together with token_2fa. If the password is the problem instead, start a reset with POST /auth/request-password-reset.

Was this page helpful?