Authentication (deprecated)

Basics

Requests to the ShareBase API are authorized via an authorization token. The token identifies a user and contains claims about them, such as what privileges they have.

An authorization token is be obtained in one of two ways:

  1. A user token can be obtained by authenticating with valid ShareBase credentials consisting of an e-mail address and password
  2. An API token can be obtained by a site admin of an organization

Typically, a user-based token would be used when creating an interactive application against ShareBase and an API token would be used when creating a non-interactive application, such as an application that periodically sweeps documents into a corporate library.

Authenticating

The ShareBase API supports Basic authentication. The e-mail address and password are Base64 encoded and passed into an Authorization header with a Basic scheme. Take the following example:

Given an e-mail address of sam.user@example.com and a password of password, concatenate the values separated by a colon.

sam.user@example.com:password

Then, Base64 encode the value. For example, sam.user@example.com:password is:

c2FtLnVzZXJAZXhhbXBsZS5jb206cGFzc3dvcmQ=

Finally, issue a GET request with an authorization header using the Basic scheme:

GET /api/authenticate
Authorization: Basic c2FtLnVzZXJAZXhhbXBsZS5jb206cGFzc3dvcmQ=

The response will return an object containing authorization and user information. Within the object, the Token property represents an authorization token that can be used to make authorized requests to ShareBase.

{
    "Token": "MDAwMDAwNzk6ZTExZDYxZjEtYzg2Zi00YTgwLTllY2YtNzJmNWIyMjFmNDZk",
    "UserName": "Sam User",
    "UserId": 1,
    "ExpirationDate": "2016-04-14T02:31:52.636682-04:00"
}

The authorization token has the following properties:

  • Token: the authorization token value to be used in subsequent API requests
  • UserName: the name of the user associated with the token
  • UserId: the user ID of the user associated with the token
  • ExpirationDate: the expiration date of the token

Invalid authentication attempts

An invalid authentication attempt, due to either using an e-mail address that is not registered or using an incorrect password for a given e-mail address, will result in an HTTP 401 Unauthorized response.

Handling expired passwords

If the authentication for the user succeeds but the password is expired, then an HTTP 403 Forbidden is returned along with the following response body:

{
    "PasswordExpired" : true
}

Authorizing requests

Once you have successfully obtained an authorization token, you can use it in subsequent requests. This is done by setting the Authorization header on each request to the API, but instead of using the Basic scheme, you would use the PHOENIX-TOKEN scheme along with the authorization token.

For example, assume you have successfully authenticated and received an authorization token like MDAwMDAwNzk6ZTExZDYxZjEtYzg2Zi00YTgwLTllY2YtNzJmNWIyMjFmNDZk. Then, in a request to retrieve libraries, you would use the PHOENIX-TOKEN scheme as follows:

GET /api/libraries
Authorization: PHOENIX-TOKEN MDAwMDAwNzk6ZTExZDYxZjEtYzg2Zi00YTgwLTllY2YtNzJmNWIyMjFmNDZk

Expired tokens

API tokens do not expire, thus you will not need to obtain a new API token once one is obtained from your site admin.

Currently the lifetime of a user token is 10 hours. When a request is made with an expired token, the response will be an HTTP 401 Unauthorized. At that point you must obtain a new authorization token.