Request Access Token

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://apidocs.zerionsoftware.com/doc/iformbuilder-v81/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "iFormBuilder V81 MCP server": {
    "url": "https://apidocs.zerionsoftware.com/doc/iformbuilder-v81/mcp"
  }
}

Close
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/v81/[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 v80 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).

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 object Required

body of a token request; the required parameters depend on grant_type

One of:
Body object Required

body of a token request; the required parameters depend on grant_type

One of:

Responses

  • 200 application/json

    OK - the access token was issued.

    Hide response attributes Show response attributes object
    • access_token string Required

      send as Authorization: Bearer {access_token}

    • token_type string Required

      Value is Bearer.

    • expires_in integer Required

      lifetime of the access token in seconds

    • refresh_token string

      present only for authorization_code with access_type=offline

  • 400 application/json

    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.

    Hide response attributes Show response attributes object
    • error string

      OAuth error code, or a jwt ... string for a rejected JWT assertion

      Values are invalid_request, unsupported_grant_type, invalid_client, unauthorized_client, invalid_grant, jwt header params, jwt claim set, jwt time, jwt client key, jwt signature, or jwt not supported.

    • 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 application/json

    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).

    Hide response attributes Show response attributes object
    • error string

      OAuth error code, or a jwt ... string for a rejected JWT assertion

      Values are invalid_request, unsupported_grant_type, invalid_client, unauthorized_client, invalid_grant, jwt header params, jwt claim set, jwt time, jwt client key, jwt signature, or jwt not supported.

    • 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

POST /oauth/token
curl \
 --request POST 'https://api.iformbuilder.com/exzact/api/v81/[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/v81/[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"
}'
Request examples
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
Request examples
{
  "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"
}
Response examples (200)
{
  "access_token": "0123456789abcdef0123456789abcdef01234567",
  "token_type": "Bearer",
  "expires_in": 3600
}
{
  "access_token": "0123456789abcdef0123456789abcdef01234567",
  "refresh_token": "76543210fedcba9876543210fedcba9876543210",
  "token_type": "Bearer",
  "expires_in": 3600
}
Response examples (400)
{
  "error": "invalid_request"
}
{
  "error": "unsupported_grant_type"
}
{
  "error": "unauthorized_client"
}
{
  "error_message": "invalid_grant"
}
{
  "error": "invalid_grant",
  "error_description": "Account not activated"
}
Response examples (401)
{
  "error": "invalid_client"
}
{
  "error": "invalid_client"
}