Authentication
Authenticate to create access tokens that are needed to make requests to the API.
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 toapplication/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
Updated about 2 months ago