Authentication

Authentication

You authenticate to the REST API with the same StorONE user accounts you use for the web interface and the CLI. You log in once to get a session token, then send that token with every request.

Logging in

POST /login
Content-Type: application/json

{
  "Username": "alice",
  "Password": "<password>"
}

Field Type Description Username string The user name. Password string The password. TwoFactorAuthenticationToken string The current two-factor code, if the account requires two-factor authentication (see below). InactivityTimeoutInMinutes integer How long the session may sit idle before it expires. Defaults to 60; the maximum is 1440 (24 hours).

A successful login returns 200 OK with a body like this (abbreviated):

{
  "Status": "Ok",
  "SessionToken": "3f2a8b1c-5d4e-4f60-9a7b-1c2d3e4f5a6b_9b8a7c6d-5e4f-4321-8765-0fedcba98765",
  "UserEmailAddress": "alice@example.com"
}

The response also includes PostLoginMessage, Systems (the systems the user can manage), and Roles. The value you need is SessionToken: a long string made of two GUIDs joined by an underscore.

Using the token

Send the token in the Authorization header of every other request, with the Bearer prefix:

Authorization: Bearer <SessionToken>

Each request you make resets the session's idle timer, so a session stays open as long as you keep using it within the inactivity timeout. If the token is wrong, or the session has expired or been logged out, the request fails with a 401 and a Status of SessionTokenDoesNotExist ("Session token does not exist and it might have timed-out. Please re-login."); log in again to get a new token.

Tip: The same Authorization header also accepts HTTP Basic credentials (Authorization: Basic <base64 of username:password>), which logs in on the fly. Prefer a session token: it keeps your password out of every request.

Two-factor authentication

If a user account requires two-factor authentication, logging in with only a username and password returns 401 with a Status of TwoFactorAuthenticationRequired. Log in again with the same username and password plus TwoFactorAuthenticationToken set to the current code from the user's authenticator.

Logging out

End the session when you're done, so the token can't be reused:

DELETE /logout
Authorization: Bearer <SessionToken>

Resetting a password

A user who has forgotten their password can request a new one. This endpoint doesn't need a token:

POST /resetpassword
Content-Type: application/json

{
  "Username": "alice",
  "Email": "alice@example.com"
}

When login fails

A failed login returns 401 Unauthorized, and the Status field in the response says why. The values you're most likely to see:

Status Meaning InvalidUsernamePassword The user name or password is wrong. TwoFactorAuthenticationRequired The account requires a two-factor code; send TwoFactorAuthenticationToken. InvalidTwoFactorAuthentication The two-factor code was wrong or has expired. InvalidPasswordExpired The password has expired and must be changed. LoginIsTemporarilyDisabledDueToFailedAttempts Too many failed attempts; wait before trying again.

A request that has no Authorization header at all, or a malformed one, is reported in the response body (MissingAuthenticationHeader or InvalidAuthorizationHeader) rather than with a 401. See Requests and responses for why you should always check Status.

A login body that asks for an InactivityTimeoutInMinutes above 1440 is rejected with 400 Bad Request.

---

Next: Requests and responses — how endpoints take parameters and return results.