How to Bytemark

Show documention menu


All API requests require a valid session token obtained from (exceptions to this are Definitions and the session requests below).

Sessions are valid for five minutes from the point of issue. Requests to read the session (GET /session/{session-id}) or successfully authenticated API requests extend this by five minutes.

Create session:

Content-Type: application/json
Accept: text/plain


  "username"  : "my-username-here",
  "password"  : "my-password-here",
  "yubikey"   : "my-optional-yubikey-otp-here"


Assuming username, password and yubikey (if provided) are correct, a 200 OK response will be returned with a text/plain body. This is the session ID.

text/plain: Session ID

Read session:

Gets session information, or verify that a session is valid.

GET{session-id} HTTP/1.1
Accept: application/json


This returns a 404 if the session does not exist, and 200 with a JSON body if it does.

  "username"          : "my-username-here",
  "factors"           : ["password", "yubikey", ...],
  "group_memberships" : ["group1", "group2"]
  • The username is the same as the POST /session request that created the session.
  • factors is an array of strings describing the credentials the user supplied to acquire the session — password and yubikey are the only ones currently.
  • A user’s groups may be altered during the lifetime of a session, so if you care about group membership, you should check every time.

Each time you GET the session with this endpoint; the session expiry time is extended by five minutes.

Authenticated requests

API requests are authenticated by sending valid session token using the Authorization header RFC6750 token

GET {api-url} HTTP/1.1
Authorization: Bearer {session-id}

Requests without a valid session token should return a HTTP 401 status.

Bytemark Cloud used to be called "BigV"—nothing has changed except the name! We’re hiring! Please visit to find out more.