Sign in Talk to us Start a trial
Start a trial

Design and software studio
Color

Signing in, tokens and lockout

Sign in on any device, understand how long you stay signed in, and know what happens after repeated wrong passwords.

For
Everyone
Hosting
Any hosting
Devices
All devices
Business
All businesses

Checked against Pop Dispatch 0.1.0

You sign in with your email address and password. The server answers with a token, and your app sends that token with every request. This article explains how long a token lasts, how to sign out, and when the server pauses sign-ins after wrong passwords.

Before you start #

  • Your owner has given you an account. Owners and managers also need the authenticator app. See "Two-step sign-in for owners and managers".
  • With more than one business account on the same server, the sign-in names the account in the tenant field. With one account on the server, you can leave it out.

Steps #

  1. Open the Sign in screen.
  2. Enter your email address and password. Capital letters in the email address make no difference.
  3. Owners and managers enter the 6 digit code from the authenticator app.
  4. Choose the device name and platform if the app asks. The platform is one of ios, android, mac, windows or web.
  5. You are in. The token lasts 90 days. Each time you use it with fewer than 30 days left, the server extends it to 90 days again, so a token in daily use stays valid.
  6. To sign out, choose Sign out. The token stops working at once on every request.

Your first password #

When an owner runs init or reset-password, you receive a one-time password. After you sign in with it, Pop Dispatch asks you to choose your own before anything else.

  1. Send your email address, the one-time password and your new password to /auth/change-password. Until you do, every other call answers password_change_required (403). GET /me and sign-out still work.
  2. Choose at least 10 characters, different from the current password.
  3. Pop Dispatch saves the new password and ends every earlier sign-in of yours. Sign in again with the new password.

What the lockout does #

  • The server counts wrong passwords and wrong codes from the last 15 minutes, by your email address and by your network address.
  • After 8 failures the server answers locked (HTTP 429) and refuses further sign-in attempts from that email or address until the oldest failures are 15 minutes old.
  • Each network address can try 20 sign-ins a minute.
  • A correct sign-in leaves a record of the attempt, so the count stays accurate.
  • An unknown account name and a wrong password give the same answer, so an outsider learns nothing about which accounts exist.
Technical details
  • Passwords are stored as argon2id hashes (19 MiB memory, 2 passes).
  • Tokens look like psdt_ followed by 39 letters and digits. The server stores only a SHA-256 hash of the token, so a copy of the database holds no usable token.
  • last_used_at and the address are written at most once a minute for each token.
  • Send the token as Authorization: Bearer <token>.
  • A deactivated account loses access at once: the server checks the account on every request and answers unauthorized with "This account is no longer active."

If something goes wrong #

  • invalid_credentials (401): the email and password pair failed, or the failure count reached the limit. Wait a few minutes and try again.
  • totp_required (401): add the 6 digit code in the totp field.
  • totp_enrolment_required (401): finish the authenticator app set-up first.
  • password_change_required (403): choose your own password first, as above.
  • locked or rate_limited (429): wait. See "API rate limits" and "API errors reference".
  • unauthorized (401) on any call: the token has ended, was revoked or was never valid. Sign in again.