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"}.HS384andHS512are also accepted. - Claims:
iss- the API app's client keyaud- 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 exampleuk-api.iformbuilder.comin the UK region). The version segment must match the version you call; av81audience is rejected here.iat- issued-at time, in Unix secondsexp- expiry time, in Unix seconds. It must be in the future, not beforeiat, and no more than 600 seconds afteriat.
- Signature: the HMAC (SHA-256, SHA-384 or SHA-512, matching
alg) ofbase64url(header) + "." + base64url(claims), keyed with the client secret and base64url-encoded.
Authorization code flow
- 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}(stateis optional but recommended: generate an unguessable value and check that it matches on return to protect against CSRF). - After the user signs in, the browser is redirected to
redirect_uriwithcode(andstate). The code expires after 5 minutes. - Exchange the code here with
grant_type=authorization_code, the sameredirect_uri, and the client credentials. Addaccess_type=offlineto also receive arefresh_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).
Responses
-
OK - the access token was issued.
-
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.
-
Unauthorized - the
client_idis unknown, theclient_secretis empty or wrong, or the JWTissis not a client key on this server (allinvalid_client).
curl \
--request POST 'https://api.iformbuilder.com/exzact/api/v80/[servername]/oauth/token' \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "Authorization: Basic base64({client_id}:{client_secret})" \
--data 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwMTIzNDU2Nzg5YWJjZGVmIiwiYXVkIjoiLi4uIiwiaWF0IjoxNzkxMjUwMDAwLCJleHAiOjE3OTEyNTA2MDB9.c2lnbmF0dXJl'
curl \
--request POST 'https://api.iformbuilder.com/exzact/api/v80/[servername]/oauth/token' \
--header "Content-Type: application/json" \
--header "Authorization: Basic base64({client_id}:{client_secret})" \
--data '{
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
"assertion": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwMTIzNDU2Nzg5YWJjZGVmIiwiYXVkIjoiLi4uIiwiaWF0IjoxNzkxMjUwMDAwLCJleHAiOjE3OTEyNTA2MDB9.c2lnbmF0dXJl"
}'
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwMTIzNDU2Nzg5YWJjZGVmIiwiYXVkIjoiLi4uIiwiaWF0IjoxNzkxMjUwMDAwLCJleHAiOjE3OTEyNTA2MDB9.c2lnbmF0dXJl
grant_type=password&username=demo_user&password=********&client_id=0123456789abcdef0123456789abcdef01234567&client_secret=fedcba9876543210fedcba9876543210fedcba98
grant_type=authorization_code&code=1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&access_type=offline&client_id=0123456789abcdef0123456789abcdef01234567&client_secret=fedcba9876543210fedcba9876543210fedcba98
grant_type=refresh_token&refresh_token=76543210fedcba9876543210fedcba9876543210&client_id=0123456789abcdef0123456789abcdef01234567&client_secret=fedcba9876543210fedcba9876543210fedcba98
{
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
"assertion": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwMTIzNDU2Nzg5YWJjZGVmIiwiYXVkIjoiLi4uIiwiaWF0IjoxNzkxMjUwMDAwLCJleHAiOjE3OTEyNTA2MDB9.c2lnbmF0dXJl"
}
{
"grant_type": "password",
"username": "demo_user",
"password": "********",
"client_id": "0123456789abcdef0123456789abcdef01234567",
"client_secret": "fedcba9876543210fedcba9876543210fedcba98"
}
{
"access_token": "0123456789abcdef0123456789abcdef01234567",
"token_type": "Bearer",
"expires_in": 3600
}
{
"access_token": "0123456789abcdef0123456789abcdef01234567",
"refresh_token": "76543210fedcba9876543210fedcba9876543210",
"token_type": "Bearer",
"expires_in": 3600
}
{
"error": "invalid_request"
}
{
"error": "unsupported_grant_type"
}
{
"error": "unauthorized_client"
}
{
"error_message": "invalid_grant"
}
{
"error": "invalid_grant",
"error_description": "Account not activated"
}
{
"error": "invalid_client"
}
{
"error": "invalid_client"
}