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"}.HS384andHS512are also accepted. - Claims:
iss- the API app's client keyaud- 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 includesv80/v81).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
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.
- 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}(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 and can be exchanged only once. - 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. 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 |
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. -
Internal Server Error - an authorization
codeorrefresh_tokenwas rejected, or another internal error occurred. See the description. -
Service Unavailable - the database is unavailable.
curl \
--request POST 'https://servername.iformbuilder.com/exzact/api/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'
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwMTIzNDU2Nzg5YWJjZGVmIiwiYXVkIjoiLi4uIiwiaWF0IjoxNzkxMjUwMDAwLCJleHAiOjE3OTEyNTA2MDB9.c2lnbmF0dXJl
grant_type=password&username=example.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
{
"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": "invalid_grant",
"error_description": "Invalid username/password combination"
}
{
"error": "invalid_grant"
}
{
"error": "invalid_client"
}
{
"error": "server_error"
}
{
"error": "service_unavailable"
}