API: Authentication

There are 4 ways to authenticate with the API:

1. Creating a session.

Posting authentication parameters in a body to POST /security. The request body should be JSON payload:

{"user":{"email":"[email protected]","password":"iamsosecretyouwillforgetmewhenyoureadme"}}

The response, if successful, will be a JSON payload of the form:

{"meta":{"status":200,"message":"OK"},"data":{"auth_token":"xxxxxxxxxxxxxxxxxxxx","user_name":"reader","message":"Logged in successfully."}}

This process will:

• respond with a set-cookie header containing the _baw_session cookie
• create (or recreate) an authentication token and return it in the response

The cookie's session expires after six hours.

2. Use a cookie

The cookie issued from the create session step can be sent back on each request. This is typically done by the browser.

Send the cookie in the Cookie header.

3. Use an authentication token

• Can be transmitted with the Authorization header in the format Authorization: Token token="xxxxxxxxxxxxxxxxxxxx"
• Via the user_token query string parameter on any URL e.g GET /projects/1?user_token=xxxxxxxxxxxxxxxxxxxx
• The current token can be retrieved from GET /security/user
• Tokens are regularly refreshed (when a new session is created, or a session is deleted)

4. Using a JWT (JSON Web Token)

• JWTs are not issued by the API, there is no exposed method for generating them.
• JWTs are only currently issued for machine-to-machine service operations
• JWTs must be transmitted in the Authorization header in the format Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
• JWTs emitted by our site will have the following claims:
  • A sub subject claim identifying the user that is authenticated by this token
  • A exp expiration claim that defaults to a 24-hour expiry
  • A nbf not before claim that is not set by default
  • An optional custom resource claim that restricts the token to a particular resource (like projects, sites, etc...)
  • An optional custom action claim that restricts the token to a particular action (like show, index, create, etc...)

Note: both the resource and action claims are additional restrictions on access. They don't bypass any of the normal authorization rules.