> For the complete documentation index, see [llms.txt](https://apidocs.zerionsoftware.com/doc/iformbuilder-v60/llms.txt)

# Request Access Token

> POST /oauth/token
> 
> Issues an access token. Send the returned `access_token` as `Authorization: Bearer {access_token}` on every other request; it grants access to any resource the token's user can access. This endpoint itself does not take a bearer token.
> 
> **URL:** `https://servername.iformbuilder.com/exzact/api/oauth/token` - note there is no `v60` segment.
> 
> Parameters must be sent in the request body as `application/x-www-form-urlencoded`. Never put credentials in the query string: query parameters are also read and override body values, and URLs end up in logs. Unknown parameters are ignored.
> 
> ### Grant types
> 
> | `grant_type` | Required parameters | Notes |
> |---|---|---|
> | `urn:ietf:params:oauth:grant-type:jwt-bearer` | `assertion` | Recommended for server-to-server API apps. No `client_id`/`client_secret`: the client key is the JWT `iss`, and the token is issued for the user the API app belongs to. |
> | `password` | `username`, `password`, `client_id`, `client_secret` | The token is issued for the iFormBuilder user in `username`. |
> | `authorization_code` | `code`, `redirect_uri`, `client_id`, `client_secret` | `redirect_uri` must match the one used on the authorize page. Optional `access_type=offline` also returns a `refresh_token`. |
> | `refresh_token` | `refresh_token`, `client_id`, `client_secret` | Returns a new access token for the user the refresh token was issued to. `code` is accepted in place of `refresh_token`. No new refresh token is returned. |
> 
> The API app must be enabled for the grant type it requests, otherwise the response is `unauthorized_client`.
> 
> ### Client authentication
> 
> For every grant except JWT bearer, send `client_id` and `client_secret` in the request body, or as HTTP Basic credentials (`Authorization: Basic base64({client_id}:{client_secret})`). Basic credentials take precedence over body values.
> 
> ### JWT bearer assertion
> 
> `assertion` is a JWT signed with the API app's client secret.
> 
> - **Header:** `{"alg": "HS256", "typ": "JWT"}`. `HS384` and `HS512` are also accepted.
> - **Claims:**
> - `iss` - the API app's client key
> - `aud` - the full URL of this endpoint on the host you send the request to: `https://servername.iformbuilder.com/exzact/api/oauth/token`. There is no version segment (unlike the v8.x API, whose audience includes `v80`/`v81`).
> - `iat` - issued-at time, in Unix seconds
> - `exp` - expiry time, in Unix seconds. It must be in the future, not before `iat`, and no more than 600 seconds after `iat`.
> - **Signature:** the HMAC (SHA-256, SHA-384 or SHA-512, matching `alg`) of `base64url(header) + "." + base64url(claims)`, keyed with the client secret and base64url-encoded.
> 
> ### Authorization code flow
> 
> Before using this flow, register the exact redirect URI(s) of your application on the API app, using `https`. If no redirect URI is registered, the authorize page will redirect to any `redirect_uri` it is given.
> 
> 1. Send the user's browser to the authorize page: `https://servername.iformbuilder.com/exzact/api/oauth/auth?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={state}` (`state` is optional but recommended: generate an unguessable value and check that it matches on return to protect against CSRF).
> 2. After the user signs in, the browser is redirected to `redirect_uri` with `code` (and `state`). The code expires after 5 minutes and can be exchanged only once.
> 3. Exchange the code here with `grant_type=authorization_code`, the same `redirect_uri`, and the client credentials. Add `access_type=offline` to also receive a `refresh_token`.
> 
> ### Response
> 
> `access_token`, `token_type` (always `Bearer`) and `expires_in` (seconds; currently 3600). `refresh_token` is included only for `authorization_code` with `access_type=offline`. Refresh tokens have no expiry time and are not rotated, so store them as securely as the client secret. Authorizing the same user for the same API app again revokes that user's earlier refresh tokens for the app.
> 
> Cache the access token and reuse it until it expires; don't request a new token for every API call.
> 
> ### Errors
> 
> Errors return a JSON object with `error`. A failed `password` grant also includes `error_description`.
> 
> | HTTP | `error` | Cause |
> |---|---|---|
> | `400` | `invalid_request` | `grant_type` or another required parameter (including `client_secret`) is missing, or `access_type`/`redirect_uri` is not valid |
> | `400` | `unsupported_grant_type` | `grant_type` is not one of the four values above |
> | `401` | `invalid_client` | `client_id` is not a known API app, `client_secret` is empty or wrong, or the JWT `iss` is not a client key on this server |
> | `400` | `unauthorized_client` | the API app is not enabled for this grant type |
> | `400` | `invalid_grant` | the `password` grant could not sign the user in (see `error_description`), or the JWT assertion is malformed or fails the header, claim, `aud`, time or signature checks |
> | `500` | `server_error` | an authorization `code` that is unknown, expired, issued to another API app or used with a different `redirect_uri`, or a `refresh_token` that is unknown or issued to another API app; also any other internal error |
> | `503` | `service_unavailable` | the database is unavailable |



## Servers
- The token endpoint is not under /v60/: https://servername.iformbuilder.com/exzact/api (The token endpoint is not under /v60/)



## Parameters
### Headers

- **Authorization** (string)
  optional HTTP Basic client authentication, e.g. Basic base64({client_id}:{client_secret}); an alternative to client_id/client_secret in the body. Not used by the JWT bearer grant.




### Body: application/x-www-form-urlencoded (object)

- **grant_type** (string)

- **assertion** (string)
  JWT signed with the API app's client secret (HS256, HS384 or HS512) carrying `iss`, `aud`, `iat` and `exp` claims



## Responses
### 200
OK - the access token was issued.

#### Body: application/json (object)
- **access_token** (string)
  send as `Authorization: Bearer {access_token}`

- **token_type** (string)

- **expires_in** (integer)
  lifetime of the access token in seconds

- **refresh_token** (string)
  present only for `authorization_code` with `access_type=offline`


### 400
Bad Request - missing or invalid parameters, an unsupported grant type, an API app not enabled for the grant, bad user credentials, or a rejected JWT assertion. See the error table in the description.

#### Body: application/json (object)
- **error** (string)
  OAuth error code

- **error_description** (string)
  human-readable reason; present only when a `password` grant cannot sign the user in


### 401
Unauthorized - the `client_id` is unknown, the `client_secret` is empty or wrong, or the JWT `iss` is not a client key on this server.

#### Body: application/json (object)
- **error** (string)
  OAuth error code

- **error_description** (string)
  human-readable reason; present only when a `password` grant cannot sign the user in


### 500
Internal Server Error - an authorization `code` or `refresh_token` was rejected, or another internal error occurred. See the description.

#### Body: application/json (object)
- **error** (string)
  OAuth error code

- **error_description** (string)
  human-readable reason; present only when a `password` grant cannot sign the user in


### 503
Service Unavailable - the database is unavailable.

#### Body: application/json (object)
- **error** (string)
  OAuth error code

- **error_description** (string)
  human-readable reason; present only when a `password` grant cannot sign the user in



[Powered by Bump.sh](https://bump.sh)
