Authentication

When working with Basiq APIs your application will need to complete the authentication process first before you can access any of the available resources.

The authentication process is fairly straight forward, and simply requires you to exchange your API key for a token. Once you obtain the token, you can call any of the available API services by simply including the token in the Authorization header of each request.

❗️
Your API keys carry many privileges, so be sure to keep them secret! Do not share your API keys in publicly accessible areas such GitHub, client-side code, etc.

Prerequisites

Prior to authenticating your application you will need to complete the following steps:

Sign-up to the Basiq API service
Grab your API key for your application (via the Developer Dashboard)

Steps to authenticate

Call /token passing in the API key in the Authorization header of the request and Basiq API version you intent to use
The server will validate the key and if everything is successful will issue an access token along with the following properties:

Property	Description
access_tokenstring, readonly	The generated access token.

token_type string, readonly	This value will always be `Bearer`.

expires_in number, readonly	The number of seconds left before the token becomes invalid.

This access token is the key to making successful requests to the Basiq API. From here on you will need to include this access token in the header when requesting any of the secured resources as follows:

Authorization: Bearer [access_token]

🚧
Note that tokens have a short lifespan and as such should not be stored permanently. Once a token has expired your application will need to reauthenticate.

Possible Errors

In the event that something goes wrong a valid HTTP status code and error object will be returned in the body of the response.


invalid-request	Status 400 Bad Request The request is missing a required parameter, includes an unsupported parameter value (other than grant type) or is otherwise malformed.

parameter-not-valid	Status 400 Bad Request Authorization header parameter is required/invalid or the older version is no longer supported

unsupported-grant-type	Status 400 Bad Request The Authorization grant type is not supported.

access-denied	Status 403 Forbidden Access to the requested resource is forbidden. This will be returned when a Basiq partner account is temporarily disabled.

parameter-not-valid	Status 404 Not Found Resource not found. This will be returned once a Basiq partner account has been deleted.

internal-server-error	Status 500 Internal Server Error A generic HTTP error message, an unexpected condition was encountered.

invalid-grant	Status 400 Bad Request The provided Authorization grant (e.g. apiKey) or token is invalid, expired or has been revoked.Error status no longer returned and to be removed from docs from Aug 21

unauthorized-client	Status 400 Bad Request The authenticated application is not authorized to use this Authorization grant type.Error status no longer returned and to be removed from docs from Aug 21

invalid-client	Status 401 Unauthorized Application authentication failed (e.g., unknown application, no authentication included, or unsupported authentication method).Error status no longer returned and to be removed from docs from Aug 21

POST /token

POST /token HTTP/1.1
Authorization: Basic YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
basiq-version: 2.1

scope=SERVER_ACCESS

👍
Token scope: CLIENT_ACCESS or SERVER_ACCESS
The scope of a CLIENT_ACCESS token is restricted and should be used on your client application to pass user credentials when creating a connection. This means that user credentials are passed straight through to Basiq and do not ever hit your server.
CLIENT_ACCESS token only grants access to the following requests:

Retrieve or list all institutions

Create a connection

Update a connection

Check job status

SERVER_ACCESS token can be used for all endpoints and has full access to create resources and retrieve data

POST /token HTTP/1.1
Authorization: Basic YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
basiq-version: 2.1

scope=CLIENT_ACCESS

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token":"YOUR_ACCESS_TOKEN",
    "token_type":"Bearer",
    "expires_in":3600
}

GET /users/ea3a81/accounts HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json