Client Credentials Grant

The following details how a client application would use the Client Credentials Grant to generate bearer tokens to authenticate Ironclad API resource requests.

Requesting a Token

Construct the token request: The token request should be a POST request to the token endpoint URL. The request body should include several parameters in JSON format, including the client ID, client secret, scope, and grant type. The format of the request should be as follows:
```
POST https://ironcladapp.com/oauth/token

  grant_type=client_credentials
  scope=SCOPE_HERE
  client_id=CLIENT_ID_HERE
  client_secret=CLIENT_SECRET_HERE
```
- The grant_type parameter should always be set to "client_credentials" for the client credentials grant.
- The scope parameter specifies the level of access that your application is requesting. It should be a space-separated string of Ironclad resource scopes that can be found on the client application registration page. The scopes requested must be equal to or a subset of the client application’s registered scopes.
- The client_id parameter is the client identifier that identifies your application to the authorization server and can be found on the client application registration page.
- The client_secret parameter is a secret that is used to authenticate your application with the authorization server. The client secret is provided when you first register your application and is unretrievable afterward. If you need to rotate or reset your secret, this can be done from the client application registration page.
- Note: The client ID and secret can be optionally included in the Authorization header prepended with the “Basic” keyword, a space, and then the client ID and secret base64 encoded with a colon separator.
Send the token request: Once you have constructed the token request, you should send it to the token endpoint URL using a POST request. The authorization server will then validate the request and respond with an access token, the granted scopes as a space-separated string, the token type, and the number of seconds until expiration.
```
{"access_token":"ACCESS_TOKEN_HERE", "scope":"SCOPE_HERE", "expires_in":21600, "token_type":"Bearer"}
```

Refreshing a Token

Issued access tokens expire after 6 hours. The client credentials grant does not produce refresh tokens. To get a new access token, just follow the initial grant directions above.

Access Token Scope

The access tokens issued as a result of the client credentials grant will be be scoped on two dimensions, resource access and entity access.

All Ironclad API endpoints are gated with a resource scope (e.g. public.workflows.createdWorkflows), which can be found in the API documentation for each endpoint. Tokens can only access a given endpoint if the associated resource scope has been granted to that token.

Additionally, requests to the Ironclad API will be scoped by the accessing entity's permissions in the system. In particular, the client credentials grant produces an access token scoped to a company but requests with that token must include either the x-as-user-id or x-as-user-email header to specify who the request is being made on behalf of within the company. API requests will be scoped to the permissions of that user within the company which includes both whether the user can perform a given action at all (e.g. a user cannot approve workflows on behalf of other users) and what data is returned (e.g. if a user only has access to a subset of record types, fetching records will return only the records the user has access to).