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-v60/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "iFormBuilder V60 MCP server": {
    "url": "https://apidocs.zerionsoftware.com/doc/iformbuilder-v60/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.

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

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.

application/x-www-form-urlencoded
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 Required

      OAuth error code

      Values are invalid_request, unsupported_grant_type, invalid_client, unauthorized_client, invalid_grant, server_error, or service_unavailable.

    • error_description string

      human-readable reason; present only when a password grant cannot sign the user in

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

    Hide response attributes Show response attributes object
    • error string Required

      OAuth error code

      Values are invalid_request, unsupported_grant_type, invalid_client, unauthorized_client, invalid_grant, server_error, or service_unavailable.

    • error_description string

      human-readable reason; present only when a password grant cannot sign the user in

  • 500 application/json

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

    Hide response attributes Show response attributes object
    • error string Required

      OAuth error code

      Values are invalid_request, unsupported_grant_type, invalid_client, unauthorized_client, invalid_grant, server_error, or service_unavailable.

    • error_description string

      human-readable reason; present only when a password grant cannot sign the user in

  • 503 application/json

    Service Unavailable - the database is unavailable.

    Hide response attributes Show response attributes object
    • error string Required

      OAuth error code

      Values are invalid_request, unsupported_grant_type, invalid_client, unauthorized_client, invalid_grant, server_error, or service_unavailable.

    • error_description string

      human-readable reason; present only when a password grant cannot sign the user in

POST /oauth/token
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'
Request examples
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
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": "invalid_grant",
  "error_description": "Invalid username/password combination"
}
{
  "error": "invalid_grant"
}
Response examples (401)
{
  "error": "invalid_client"
}
Response examples (500)
{
  "error": "server_error"
}
Response examples (503)
{
  "error": "service_unavailable"
}