> For the complete documentation index, see [llms.txt](https://apidocs.zerionsoftware.com/doc/iformbuilder-v80/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.
> 
> Parameters can be sent as `application/x-www-form-urlencoded` or `application/json`. 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, including the API version and server name: `https://api.iformbuilder.com/exzact/api/v80/[servername]/oauth/token`. Use the host you send the request to (for example `uk-api.iformbuilder.com` in the UK region). The version segment must match the version you call; a `v81` audience is rejected here.
> - `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
> 
> 1. Send the user's browser to the authorize page on your iFormBuilder server: `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.
> 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`.
> 
> Cache the access token and reuse it until it expires; don't request a new token for every API call.
> 
> ### Errors
> 
> Most errors return a JSON object with `error`. A failed `password` grant also includes `error_description` when the failure is a known sign-in outcome (invalid credentials, inactive account or company, locked account, SSO required, expired session); an unexpected server-side failure returns `invalid_grant` with no description.
> 
> | HTTP | `error` | Cause |
> |---|---|---|
> | `400` | `invalid_request` | `grant_type` or another required parameter (including `client_secret`) is missing, a parameter is not a string, 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 (including the JWT bearer grant) |
> | `400` | `invalid_grant` | the `password` grant could not sign the user in (see `error_description`, omitted for unexpected server-side failures), or the `assertion` was rejected: not a three-part JWT, the header is missing `alg`/`typ` or `alg` is not `HS256`, `HS384` or `HS512`, `iss`, `iat` or `exp` is missing, `aud` does not match this endpoint's URL, `exp` is in the past, before `iat` or more than 600 seconds after `iat`, or the signature does not match the client secret |
> 
> 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, returns `400` with `{"error_message": "invalid_grant"}` (an `error_message` key, not `error`).



## Servers
- https://api.iformbuilder.com/exzact/api/v80/[servername]: https://api.iformbuilder.com/exzact/api/v80/[servername]



## 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/json (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, or a `jwt ...` string for a rejected JWT assertion

- **error_description** (string)
  human-readable reason; present only when a `password` grant fails with a known sign-in outcome (invalid credentials, inactive account or company, locked account, SSO required, expired session); omitted for unexpected server-side failures

- **error_message** (string)
  returned instead of `error` (value `invalid_grant`) when an authorization `code` or `refresh_token` is rejected


### 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 (all `invalid_client`).

#### Body: application/json (object)
- **error** (string)
  OAuth error code, or a `jwt ...` string for a rejected JWT assertion

- **error_description** (string)
  human-readable reason; present only when a `password` grant fails with a known sign-in outcome (invalid credentials, inactive account or company, locked account, SSO required, expired session); omitted for unexpected server-side failures

- **error_message** (string)
  returned instead of `error` (value `invalid_grant`) when an authorization `code` or `refresh_token` is rejected



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