Authorization Scopes

Understanding and using the Scope Parameter.


When a credential is issued, there are permissions associated with it. For customers, the permissions are set when generating the credentials.

When making an authentication request, the scope parameter specifies the authorization scopes (permissions) that will be included in the issued token. These authorization scopes are then used by the API to authorize access.

For example, if your use case requires access to employee and performance evaluation data, your access token will need to include the employees-read and performance-evaluations-read permissions.


The scope parameter takes the following form:

scope=target-entity:<entity id>:<comma separated list of permissions>

The target entity represents the system you would like access to. In our case, we need to pass the entity id for the Culture Amp API.

The identifier differs between our production and sandbox environments so it will need to be set according to the environment being called.

The permissions are a comma-separated list of the permissions that you would like to include in your access token.

Target Entity IDs

Entity IDDescription
8ed17dce-9eca-4383-a9e1-54f82c362b6dThe entity id to use when calling the production API
79040b4d-3e2b-4480-a061-2e230eeb83b2The entity id to use when calling the sandbox API


employees-readProvides access to basic employee data
employee-demographics-readProvides access to employee demographic data
performance-evaluations-readProvides access to performance evaluation data

How do I know what permissions I'll need?

The API Specification includes the permissions needed for each endpoint.

  1. Work out what data you will need
  2. Review the API Specification to determine what endpoints you will need to call to get your required data
  3. Based on endpoints you need to call, you should be able to determine the permissions you will need to include in your access token.

Example authentication request with the scope parameter set

The below illustrates a production request for an access token that includes the employees-read and performance-evaluations-read permissions.

curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "scope=target-entity:8ed17dce-9eca-4383-a9e1-54f82c362b6d:employees-read,performance-evaluations-read" \
-d "client_id=12345-abcde" \
-d "client_secret=superSecret" \