Authentication

A browser signs in with login and receives a session cookie. A program sends a service account's key as a bearer token. Every call carries one or the other.

Session cookie

POST /api/auth/login with email and password. The response sets an HTTP-only cookie, and the browser sends the cookie on every later call. A session ends after a period of inactivity and after a maximum lifetime; both are set in the Authentication configuration. POST /api/auth/logout ends the session.

Bearer token

A program authenticates with a service account's key, sent in the Authorization header of every call. There is no sign-in call and no session, and the key does not expire; it stops working when an administrator rotates it or deletes the service account. See Service accounts.

$ curl -s -X POST http://127.0.0.1:9020/api/user/getUserProfile \
    -H "Authorization: Bearer $SEARCH2O_SERVICE_KEY" -H "Content-Type: application/json" -d '{}'

Calls are recorded against the service account, with its role, in the usage report.

Setting or resetting a password

emailCode sends a one-time code to the user's email address, and createPasswordWithEmailCode sets a new password with that code. A new user sets a first password the same way; the GUI's New user / Forgot password link is these two calls. A reset signs out every session of the user. The password rules are available from getPasswordHelp, so a client can show them before the user types.