When using the Asset Bank API the recommended method of authorization is OAuth2. OAuth2 is a secure method of authentication that allows users to authenticate as their Asset Bank user, giving them the same permissions they would have in the front-end.

OAuth2 Workflow

Adding new OAuth2 Credentials

The first step to authenticating with OAuth2 is to set up the credentials for you application in Asset Bank. As an admin user, navigate to the Admin > System > API area and click 'Add new OAuth2 credentials'.

Your OAuth2 credentials must be given a name and a description is optional. A client ID is generated for you automatically but clicking the 'Generate' link will generate a new 32-character hex string. The client secret is not generated by default but similarly the 'Generate' link will generate a 64-character hex string for you.

The redirect URIs are a list of comma-separated URIs within the application that will receive the callback during the Authorization Code grant which we will discuss later. The redirect URIs need to be https if you are not using localhost.

Authorizing Against Asset Bank

The Asset Bank OAuth2 server supports two types of grant types: the Authorization Code Grant and the Password Grant. The Authorization Code Grant is somewhat more secure but requires additional steps. Below are instructions on how to use these two grant types, using Postman to replicate your application.

Authorization Code Grant

The Authorization Code Grant has two stages. The first is to obtain an authorization code from the Asset Bank OAuth2 server.

To do so your application should direct the user's web browser to the authorization endpoint /oauth/authorize with the following parameters:

• response_type: code
• client_id: [the client ID you set in Asset Bank]
• redirect_uri: [the redirect URI you set in Asset Bank, must be an exact match]
• state (optional): will be returned unmodified to your redirect_uri, it can be used by your application to store request-specific data and/or prevent CSRF attacks.

After validating the client ID and redirect URI, Asset Bank will ask the user to log in. This authorizes your application to obtain access to the API resource as that user.

For example, given the following authorization request:

https://example.assetbank.app/assetbank-example/oauth/authorize?response_type=code&client_id=someclientid&state=somestatevalue&redirect_uri=https://example.assetbank.app/callback

The user will be prompted to log in, granting access to the user profile. Asset bank will then redirect the user to the redirect URI with the authorization code and the state if one was specified.

https://example.assetbank.app/callback?code=00000000000000000000000000000000&state=somestatevalue&expires_in=30

The authorization code is valid for 30 seconds and will need to be exchanged for an access token.

The second step is to exchange the authorization code for an access token. To obtain the access token your application will need to POST the following parameters to the /oauth/token endpoint:

• grant_type: authorization_code
• client_id: [the client ID you set in Asset Bank]
• client_secret: [the client secret you set in Asset Bank]
• redirect_uri: [the redirect URI you set in Asset Bank, must be an exact match]
• code: [the authorization code from the first step]

For example:

https://example.assetbank.app/assetbank-example/oauth/token?grant_type=authorization_code&redirect_uri=http://localhost/callback&client_id=someclientid&client_secret=someclientsecret&code=youraccesscode

You will also need to set the authorization type to Bearer Token and specify the request header Content-Type: application/x-www-form-urlencoded.

The response will provide you with an access token that is valid for 60 minutes. A refresh token is given for when the access token expires.

Password Grant

With this grant your application will be able to exchange the user's username and password for an access token. Because you are passing the username and password in the request this method should only be used with in-house integrations on self-hosted servers. Never allow third-party apps to use it.

For this grant, your application simply needs to POST the following parameters to the /oauth/token endpoint:

• grant_type: password
• client_id: [the client ID you set in Asset Bank]
• client_secret: [the client secret you set in Asset Bank]
• username: [the user's username]
• password: [the user's password]

For example:

https://example.assetbank.app/assetbank-example/oauth/token?grant_type=password&client_id=someclientid&client_secret=someclientsecret&username=username&password=password

As with the Authorization Grant you will need to specify the request header Content-Type: application/x-www-form-urlencoded.

Token Introspection

The token introspection endpoint returns information about an access token. Your application needs to POST the following parameter to the /oauth/token_info endpoint:

• token: [access token obtained through either authorization grant]

For example:

https://example.assetbank.app/assetbank-example/oauth/token_info?token=youraccesstoken

Set the authorization type to Bearer Token. The request will need to be authenticated with HTTP Basic Authentication using your client credentials. To do so, combine the client ID and client secret you set in Asset Bank with a colon and base64 encode it. Eg

client_id:client_secret   === base64 encode ===> [your encoded string]

Include this as a header in the form:

• Authorization: Basic [your encoded string]
• Content-Type: application/x-www-form-urlencoded

The response will contain the active status of the token, the client ID, the username authenticated against and the expiry of the token, represented as a unix timestamp.

Refresh Token

When the access token expires you can obtain a new set of tokens using the refresh token. To do so your application needs to POST the following parameters to the /oauth/token endpoint:

• grant_type: refresh_token
• client_id: [the client ID you set in Asset Bank]
• client_secret: [the client secret you set in Asset Bank]
• refresh_token: [the refresh token obtained through either authorization grant]

For example:

https://example.assetbank.app/assetbank-example/oauth/token?grant_type=refresh_token&client_id=someclientid&client_secret=someclientsecret&refresh_token=yourrefreshtoken

Again, set the header to include Content-Type: application/x-www-form-urlencoded.

You will receive a new access token and refresh token in the response.

Authenticating API Requests

Now that you have your access token you can use it to make API requests. To do so set the authorization type to Bearer Token and your header should include the authorization token in the form:

• Authorization: Bearer [your access token]
• Accept: application/json