How to Bytemark

Authentication

All API requests require a valid session token obtained from https://auth.bytemark.co.uk (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:

POST https://auth.bytemark.co.uk/session HTTP/1.1
Content-Type: application/json
Accept: text/plain

Parameters

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

Response

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 https://auth.bytemark.co.uk/session/{session-id} HTTP/1.1
Accept: application/json

Response

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 careers.bytemark.co.uk to find out more.