Assemble Developer Portal

OAuth 2.0 Authentication

Assemble has a wide range of API endpoints, from viewing public opportunities to updating users. Depending on the API endpoint you are using, you may need to authenticate before you can perform a particular request.

Assemble API supports OAuth 2.0 as an authentication method to enable third-party developers to integrate with Assemble.

Within the Assemble settings, you can set up OAuth 2.0 clients that will enable you to use the support authentication flows described within this documentation.

Please note that you may need to contact Assemble Support to enable OAuth 2.0 for your organisation in order to authenticate requests using this feature.

Supported flows

Assemble currently supports the following authorisation flows:

  • Client credentials: used with application API access
  • Authorisation code: used with server-side applications

We do not support implicit flow or password grant.

Scopes

Assemble leverages OAuth scopes to limit a client to specific resources within the Assemble API. The following scopes are accepted when creating access tokens:

  • activities Access resources relating to activities
  • address-book Access resources relating to address book
  • opportunities Access resources relating to opportunities
  • organisation Access resources relating to your organisation
  • role-profiles Access resources relating to role profiles
  • teams Access resources relating to teams
  • users Access resources relating to user details

Creating a client

You can create a client to use OAuth 2.0 from within the Assemble settings.

A client is necessary so that you can define the callback URI and acting user.

The acting user is the user that will be used when performing API calls when authenticating using the client credentials grant. This means that the acting user will need to have an appropriate role that gives them the correct permission to access the scopes that you require.

Client credentials flow

Once you have a client set up, you can use the client ID and secret to request an access token from Assemble.

  1. Request access token
POST /oauth/token
Name Type Description
grant_type string Required. The client credentials grant (client_credentials)
client_id string Required. The ID of your client
client_secret string Required. The secret of your client
scope string List of required scopes (space separated)
  1. Consuming Assemble API

Now that you have an access token, this can be used as the authorisation bearer within the header of a request to access protected routes.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZGlzcGxheV9uYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.Boca2nntRviOO8IdiP4CZPnMmwZZ5be4Zoen60PswDo

Authorisation code flow

Once you have a client set up, you can use the client ID and redirect URI to request an authorisation code and access token from Assemble.

  1. Request a users identity
GET /oauth/authorize
Name Type Description
client_id string Required. The ID of your client
redirect_uri string Required. The URI in your application where users will be sent after authorisation
response_type string Required. The type of response (code)
scope string List of required scopes (space separated)
state string A random string used to prevent CSRF attacks
  1. Redirect back to your site

If the request is accepted, Assemble will redirect back to your site with a temporary code and state parameters. You should ensure that the state parameter matches the one you provided within the previous request.

You can now exchange your code for an access token:

POST /oauth/token
Name Type Description
grant_type string Required. The authorisation grant (authorization_code)
client_id string Required. The ID of your client
client_secret string Required. The secret of your client
redirect_uri string Required. The URI in your application where users will be sent after authorisation
code string Required The code from the previous request

Within the response of this request, you will receive the access_token that you can use to authenticate with the Assemble API, refresh_token that can be used to refresh the access token once it expires and expires_in which indicates how long the access token is valid for (in minutes).

  1. Consuming Assemble API

Now that you have an access token, this can be used as the authorisation bearer within the header of a request to access protected routes.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZGlzcGxheV9uYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.Boca2nntRviOO8IdiP4CZPnMmwZZ5be4Zoen60PswDo

Refreshing access token

If your access token expires, you will need to refresh the access token in order to perform any further requests to protected routes. This can be done by performing the following request:

POST /oauth/token
Name Type Description
grant_type string Required. The refresh token grant (refresh_token)
client_id string Required. The ID of your client
client_secret string Required. The secret of your client
refresh_token string Required. The refresh token
scope string List of required scopes (space separated)

Prevent CSRF attacks

To prevent CSRF attacks when using redirect-based flows (such as the authorisation grant), the OAuth specification recommends using one-time CSRF tokens when redirecting. This can be achieved via the state parameter that is available to you. You can find more information about this within OAuth 2.0 specification.