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.