The Culture Amp API uses the OAuth2 client credentials flow for authentication. This flow is used when access is granted between two systems and not on behalf of an individual user.

In order to authenticate, the first thing you will need is a client id and client secret. If you don't yet have these, please see the previous steps for how to go about obtaining them.

Requesting an access token

Once you have a set of client credentials, you can exchange these for an access token. This is a short lived JSON Web Token (JWT) that will allow you to call the API.

Example token endpoint request

curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "scope=target-entity:<entity id>:<comma separated list of permissions>" \
-d "client_id=<client id>" \
-d "client_secret=<client secret>" \
https://api.cultureamp.com/v1/oauth2/token

Alternatively, the client id and secret can be passed via the request header using the Basic Authorization Scheme. For this concatenate the client id and client secret with :, then encode to Base64 and prepend with the string Basic. For example:

curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic <base64 encoded client id and secret>" \
-d "grant_type=client_credentials" \
-d "scope=target-entity:<entity id>:<comma separated list of permissions>" \
https://api.cultureamp.com/v1/oauth2/token

📘
Scope and permissions
You will no doubt have questions about the scope parameter. This is explained in the next section.

Example response

{
  "access_token": "here I am",
  "expires_in": 3599,
  "scope":"target-entity:8ed17dce-9eca-4383-a9e1-54f82c362b6d:employees-read,performance-evaluations-read",
  "token_type":"Bearer"
}

Using the access token

When calling API endpoints, the access token must be pass in a Authorization header as a Bearer Token.

curl -H "Authorization: Bearer <access token>" \
https://api.cultureamp.com/v1/employees