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 give access to API Apps

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:

The base string for the signature is as follows:

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.

 The Base64url representation of this is as follows:

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.

The JSON representation of the required fields in a JWT claim set is shown below:

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:

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

Below is an example of a JWT before Base64url encoding:

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:

with the following parameters (POST request):

if the request is successful, an access token (expires in 3600 seconds) will be returned: