Authentication

Acquired.com uses the OAuth 2.0 authorisation framework to grant applications access to our resources. This authentication method requires you to pass a bearer token value in the HTTP authorization header of your requests, which you can generate by passing your client credentials through the login endpoint.

Each developer will have their own app_id and app_key that they will use to log into the API. At this point we check that their details are correct (i.e from a known IP address) and process and return an access token. It is important to note that access tokens are valid for 1 hour, after that time a new token will need to be generated. The developer can then use this access token to authenticate themselves and log into the API. IP addresses must be added to the allowlist in order to access the API, if not access will be denied.

📘

Note

You will have different keys for both the test and production environments, you will only be able to authenticate with the specified endpoint.

Authorisation flow

See the below diagram demonstrating our authorisation flow:

Authenticate with our API

Authentication URLs

QA URL: https://test-api.acquired.com/v1/login

Production URL: https://api.acquired.com/v1/login

📘

Note

Please view our create an access_token reference guide for further information on our /login endpoint.

Step 1: Obtain your app_id and app_key values

The first thing you will need to do is locate your app_id & app_key which will be used to request an access token.

1. Firstly, log into the Hub.
2. Navigate to Settings > API Access.
3. Click into the app_key field to expose the app_key.
4. Copy and paste both values which can then be used within the code.

Step 2: Retrieve an access token from the authorisation server

Before your application can access our API, it must generate an access_token value.

Populate the app_id and app_key values with your client credentials.

Request:

{
  "app_id": "98434376",
  "app_key": "843a8fjei768fa...."
}

Response:

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

Step 3: Send the access token to the Acquired.com API

After your application retrieves an access token, it can access our API.

Pass the token through to the resource in a authorization request header.

The token expires after 1 hour, however, you may chose to generate a new one for every request.

Step 4: Obtain a new token (if required)

Access tokens have a limited timeframe of 1 hour. If your application is returned a 401 Unauthorized then your current access token may have expired.

In the case that you receive a 401 error response, obtain a new access_token (as per step 2).

See below for a sample response body:

{
    "status": "error",
    "error_type": "unauthorized",
    "title": "Authentication with the API failed, please check your details and try again.",
    "instance": "/v1/payment-link"
}

Step 5: Make your first API request

You now have the required information to make your first API request!