Authentication

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 step: Generating Credentials for how to go about obtaining them.

Requesting an Access Token

Once you have credentials, you can use them to produce an access token. This is a short-lived JSON Web Token (JWT) that will allow you to make valid requests to the API. Note that the token inherits the permissions you scoped into the credential used to create it.

Example Token Endpoint Request

📘

Content-Type Header

The Content-Type header must be set to application/x-www-form-urlencoded, and the request body must be form encoded data.

curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "scope=target-entity:<entity id>:<comma separated list of permissions>" \
--data-urlencode "client_id=<client id>" \
--data-urlencode "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>" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "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 passed in an Authorization header as a Bearer Token.

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