Authorization Code Grant

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

Requesting a Token

Construct the authorization request URL: The authorization request should be a GET request to the authorize endpoint URL. The authorization request URL should include several query parameters, including the response type, client ID, redirect URI, and scope. The format of the URL should be as follows:
```
GET https://ironcladapp.com/oauth/authorize?
  response_type=code
  &client_id=CLIENT_ID_HERE
  &redirect_uri=REDIRECT_URI_HERE
  &scope=SCOPE_HERE
  &state=STATE_HERE
```
- The response_type parameter should always be set to "code" for the authorization code grant.
- 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 redirect_uri parameter is the URI that the authorization server will redirect the user's browser to after authentication. The redirect_uri must be one of the registered redirect URIs on the client application registration page.
- Optional: 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.
- Optional: The stateparameter is used to maintain state information between the client application and the authorization server during the OAuth authorization request and response exchange. By including a randomly generated and cryptographically secure value in the "state" parameter, the client can verify that the response from the authorization server corresponds to the original request.
Redirect the user's browser to the authorization request URL: Once you have constructed the authorization request URL, you should redirect the user's browser to that URL. This can be done using a simple HTTP redirect response, or by rendering a link or button on a web page that the user can click on.
The user authenticates with the authorization server: Once the user is redirected to the Ironclad authorization endpoint, they will be prompted to log in and consent to your application's request for access to their resources.
The authorization server responds with an authorization code: If the user successfully authenticates and consents to the request, the authorization server will redirect the user's browser back to your application's redirect URI with a code query parameter with the authorization code in the URL. If a state param was included in the authorization request, that will be included as well.
```
REDIRECT_URI_HERE>>/?code=AUTHORIZATION_CODE_HERE&state=STATE_HERE
```
- If the user denies the request, the authorization server will redirect the user's browser back to your application's redirect URI with an error query parameter of “access_denied” in the URL.
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 authorization code, client ID, client secret, redirect URI, and grant type. The format of the request should be as follows:
```
POST https://ironcladapp.com/oauth/token

  grant_type=authorization_code
  code=AUTHORIZATION_CODE_HERE
  redirect_uri=REDIRECT_URI_HERE
  client_id=CLIENT_ID_HERE
  client_secret=CLIENT_SECRET_HERE
```
- The grant_type parameter should always be set to "authorization_code" for the authorization code grant.
- The code parameter is the authorization code that your application received from the authorization server.
- The redirect_uri parameter is the URI that the authorization server will redirect the user's browser to after authentication. The redirect_uri must be one of the registered redirect URIs on the client application registration page and must be the same redirect URI included in the authorization request.
- 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, instead of included in the request body.
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, a refresh token, the granted scopes as a space-separated string, the token type, and the number of seconds until expiration.
```
{"access_token":"ACCESS_TOKEN_HERE", "refresh_token":"REFRESH_TOKEN_HERE", "scope":"SCOPE_HERE", "expires_in":21600, "token_type":"Bearer"}
```

Refreshing a Token

Issued access tokens expire after 6 hours. Refresh tokens do not expire, but are reissued upon a successful access token refresh. To get a new access token, send a refresh request to the token endpoint using the refresh token. Note that a successful refresh will issue BOTH a new access token and a new refresh token.

Construct the token refresh request: The token refresh request should be a POST request to the token endpoint URL. The request body should include several parameters in JSON format, including the refresh token, client ID, client secret, and grant type. The format of the request should be as follows:
- The grant_type parameter should be set to "refresh_token" for the token refresh grant.
- The refresh_token parameter is the refresh token that was obtained during the initial authorization grant.
- 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.
- Optional: 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 and the previously granted scopes. If omitted, the token will be refreshed with the previously granted scopes.
- 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, instead of included in the request body.
Send the token refresh request: Once you have constructed the token refresh request, you should send it to the token endpoint URL with a POST request. The authorization server will then validate the request and respond with a new access token, a new refresh token, the granted scopes as a space-separated string, the token type, and the number of seconds until expiration.
```
{"access_token":"ACCESS_TOKEN_HERE", "refresh_token":"REFRESH_TOKEN_HERE", "scope":"SCOPE_HERE", "expires_in":21600, "token_type":"Bearer"}
```

Access Token Scope

The access tokens issued as a result of the authorization code 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. In addition, in the authorization code grant, the requested resource scopes will be surfaced to the consenting user on the consent dialog.

Additionally, requests to the Ironclad API will be scoped by the accessing entity's permissions in the system. In particular, the authorization code grant produces an access token scoped to the consenting user in their company context. In the case where a user is in multiple companies, they will be prompted to select a company to grant access for in the consent dialog. API requests will be scoped to the permissions of the user within that 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).