Authorization Scopes
Understanding and using the Scope Parameter.
Permissions
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.
Format
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 ID | Description |
|---|---|
| 8ed17dce-9eca-4383-a9e1-54f82c362b6d | The entity id to use when calling the production API |
| 79040b4d-3e2b-4480-a061-2e230eeb83b2 | The entity id to use when calling the sandbox API |
Permissions
| Permission | Description |
|---|---|
| employees-read | Provides access to basic employee data |
| employee-demographics-read | Provides access to employee demographic data |
| performance-evaluations-read | Provides access to performance evaluation data |
| surveys-read | Provides access to engagement survey data |
How do I know what permissions I'll need?
The API Specification includes the permissions needed for each endpoint.
- Work out what data you will need
- Review the API Specification to determine what endpoints you will need to call to get your required data
- 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" \
https://api.cultureamp.com/v1/oauth2/token
Updated 3 months ago