iFormBuilder API
In order to leverage iFormBuilder APIs, you must create an API application, or have an admin create one for you. Depending on your account configuration, the API apps menu will be under the Server Admin tab or the Company tab.
Table of Contents
- How do I generate an API Client?
- How do I generate a JSON Web Token (JWT)?
- How I request an Access Token?
Also check out:
How do I generate an API Client?
STEP 1. From the Admin Console, hover over the Server Admin tab and select API Apps.
PLEASE NOTE: If you're on app.iformbuilder.com, this will be under the Company tab.
STEP 2. Click the New Client button.
STEP 3. Name your API Client and choose the Authentication Type and click OK.
STEP 4. Highlight the user that will have access to the client and click Select User.
Take note of the Key and Secret and pass this information along to your developer or platform integrator.
Button Description:
Create a new client, with random client key and client secret, with the current logged in user. | |
Reset client secret of the selected client. | |
Delete the selected client. | |
Get a new access token with the key/secret pair (for testing), token expired in an hour as usual. | |
For backward compatibility, click this button to show users the old client key (server ID based) and generate a refresh/access token pair. |
Users can generate an access token (expires in 3600 seconds) directly from the key/secret pair, and no longer require a Refresh Token to request a new Access Token.
How do I generate a JSON Web Token?
A JWT is composed of three parts: a header, a claim set, and a signature. The header and claim set are JSON objects. These JSON objects are serialized to UTF-8 bytes, then encoded using the Base64url encoding. This encoding provides resilience against encoding changes due to repeated encoding operations. The header, claim set, and signature are concatenated together with a ‘.’ character.
A JWT is composed as follows:
{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature} |
The base string for the signature is as follows:
{Base64url encoded header}.{Base64url encoded claim set} |
JWT Header:
The header consists of two fields that indicate the signing algorithm and the format of the assertion. Both fields are mandatory, and each field has only one value. As additional algorithms and formats are introduced, this header will change accordingly.
iFormBuilder supports HMAC SHA-256, HMAC SHA-512, HMAC SHA-384 and the JWT token format.
{"alg":"HS256","typ":"JWT"} |
The Base64url representation of this is as follows:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 |
JWT Claim Set:
The JWT claim set contains information about the JWT including the target of the token, the issuer, the time the token was issued, and the lifetime of the token. All of the fields are mandatory. Similar to the JWT Header, the JWT claim set is a JSON object and is used in the calculation of the signature.
iss |
Client key of the application |
aud |
The URL of the intended target of the assertion, the value is always https://ServerName.iformbuilder.com/exzact/api/oauth/token |
exp |
The expiration time of the assertion measured in seconds since 00:00:00 UTC, January 1, 1970. This value has a maximum of *10 minutes* from the issued time. |
iat |
The time the assertion was issued measured in seconds since 00:00:00 UTC, January 1, 1970. |
The JSON representation of the required fields in a JWT claim set is shown below:
{ "iss": "1d38f6a6c89c868b6de90819d9b4e46ee6bfd05a", "aud": "https://company.iformbuilder.com/exzact/api/oauth/token", "exp": 1384370238, "iat": 1384370228 } |
The Base64url representation of this is as follows:
ewogICAgImlzcyI6ICIxZDM4ZjZhNmM4OWM4NjhiNmRlOTA4MTlkOWI0ZTQ2ZWU2YmZkMDVhIiwKICAgICJhdWQiOiAiaHR0cHM6Ly9jb21wYW55Lmlmb3JtYnVpbGRlci5jb20vZXh6YWN0L2FwaS9vYXV0aC90b2tlbiIsCiAgICAiZXhwIjogMTM4NDM3MDIzOCwKICAgICJpYXQiOiAxMzg0MzcwMjI4Cn0
JWT Signature:
JSON Web Signature (JWS) is the specification that guides the mechanics of generating the signature for the JWT. The base string of the signature is as follows:
{Base64url encoded header}.{Base64url encoded claim set} |
The signing algorithm in the JWT header must be used when computing the signature. This is expressed as “HS256” in the “alg” field in the JWT header.
Sign the base string with the provided client secret, and Base64url encode the signature.
The signature must then be Base64url encoded. The signature is then concatenated with a “.” character to the end of the Base64url representation of the input string. The result is the JWT. It should be the following (line breaks added for clarity):
{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature} |
Below is an example of a JWT before Base64url encoding:
{"alg":"HS256","typ":"JWT"}. { "iss": "1d38f6a6c89c868b6de90819d9b4e46ee6bfd05a", "aud": "https://company.iformbuilder.com/exzact/api/oauth/token", "exp": 1384370238, "iat": 1384370228 }. [signature bytes] |
Below is an example of a JWT (with client secret “6b19083c7f0889cdb7035a1f845320a298810cb0”):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICAgImlzcyI6ICIxZDM4ZjZhNmM4OWM4NjhiNmRlOTA4MTlkOWI0ZTQ2ZWU2YmZkMDVhIiwKICAgICJhdWQiOiAiaHR0cHM6Ly9jb21wYW55Lmlmb3JtYnVpbGRlci5jb20vZXh6YWN0L2FwaS9vYXV0aC90b2tlbiIsCiAgICAiZXhwIjogMTM4NDM3MDIzOCwKICAgICJpYXQiOiAxMzg0MzcwMjI4Cn0.H4FrISGS5lGiREX9bodxh7U-KVMHo7HgFh0N-LqdlI0
STEP 3: Requesting an Access Token
After generating the signed JWT, an application may use it to make an access token request. It uses the regular OAuth 2.0 token endpoint:
https://ServerName.iformbuilder.com/exzact/api/oauth/token |
with the following parameters (POST request):
grant_type |
must match “urn:ietf:params:oauth:grant-type:jwt-bearer” |
assertion |
The signed JWT |
if the request is successful, an access token (expires in 3600 seconds) will be returned:
{ "access_token": "1fb62d8998d360b46958a911c3965ed63b87cd89", "token_type": "Bearer", "expires_in": 3600 } |
Comments
0 comments
Please sign in to leave a comment.