Authz requests typically takes one of two forms. Either a user is authenticated in a browser and has a session cookie, or you are calling the API from a remote server (a machine to machine request).

Machine to machine exchanges are the most common scenario and these use the OAuth 2.0 Client Credentials flow.

​
OAuth 2.0

OAuth 2.0 is a wide standard for authorising requests to APIs. It is a protocol that allows a user to grant limited access to their resources on one site, to another site, without having to expose their credentials.

The Client Credentials flow is the most common flow for machine to machine requests. This flow is used when the client application is acting on its own behalf, rather than on behalf of a user. This is how you should authenticate requests to the Ctrl Hub API when building an integration.

If you need to access data on behalf of an indivdual user, please get in touch so we can discuss the best way to do this.

1

Service Accounts

To call the API from a remote server, first you will need to create a service account. This can be done in the UI, or via the API if you already have a service account that can create one on your behalf.

To create a new service account in the dashboard, first log in to the dashboard and then select the organisation you want to create an account for. Navigate to Admin > IAM > Service Accounts and select create a new service account. Once created, you can then create a new key which is a Client ID / Secret pair. You’ll need these to authenticate your requests to the API.

2

Exchanging Client Credentials for an Access Token

Using your service accounts’ Client ID and secret, you should exchange these for an access token. This token is then used to authenticate requests for resources from the API.

An access token has a lifetime, and the response with the access token will tell you how long it is valid for. If the access token has expired, or is not valid, requests to the API will return a 401 status code. When expired, you can request a new token from the OAuth2 API.

For example, this curl requests, piped to jq will return an access token payload.

3

Using the Access Token to make requests for Resources

You can then use the access_token in the Authorization header of your requests to the API.

It’s as simple as that! You’ve now authorised your service account by exchanging the credentials for an access token and can make requests to the API.

The API will validate the token and return the requested resources if your service account has the correct permissions set.

Useful ReadingOrganisation Model