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:

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

Steps to authenticate

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

Property

Description

access_token
string, 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.0

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:

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.0

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

Did this page help you?