Authentication

Token Authentication (Preferred)

Authentication to the GoFormz API is achieved with standard OAuth 2 specifications. This process includes obtaining an encrypted and signed JWT token from our server, which validates a user's identity, instead of using a basic username and password.

To achieve this authentication, you must follow a 3-step process:

Step 1: Setup your API Credentials

Go to the Settings page in your GoFormz account, and click on API Credentials.
Select a user, from the drop-down, to impersonate for your API requests. This will create a client secret for you, which you will use in the next step.
Make sure to copy your Client Secret, as it will not be available again. However, you can regenerate a new one.

Step 2: Get an access token

Make a POST request to https://accounts.goformz.com/connect/token with your Client ID and Secret obtained from Step 1.
As shown in the examples below, you will need to include a scope and grant_type.

POST /connect/token HTTP/1.1
Host: https://accounts.goformz.com
Content-Type: application/x-www-form-urlencoded
scope=public_api&grant_type=client_credentials&client_id=`{Client Id}`&client_secret=`{Client Secret}`

curl --location --request POST 'https://accounts.goformz.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'scope=public_api' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=`{Client Id}`' \
--data-urlencode 'client_secret=`{Client Secret}`'

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");

var urlencoded = new URLSearchParams();
urlencoded.append("scope", "public_api");
urlencoded.append("grant_type", "client_credentials");
urlencoded.append("client_id", "`{Client Id}`");
urlencoded.append("client_secret", "`{Client Secret}`");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: urlencoded,
  redirect: 'follow'
};

fetch("https://accounts.goformz.com/connect/token", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

📘
Access Token Lifetime

Our access tokens will expire in 3600 seconds (1 hour).

To avoid performance and throttling issues, it is recommended to only get a new access token once your existing token is expired, or nearly expired.

An expired access token will result in an Unauthorized request.

Step 3: How to use your access token

Use the Bearer Authorization header, as shown in the examples below.

GET /v2/formz HTTP/1.1
Host: api.goformz.com
Authorization: Bearer `{access_token}`

curl --location --request GET 'https://api.goformz.com/v2/formz' \
--header 'Authorization: Bearer `{access_token}`'

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer `{access_token}`");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://api.goformz.com/v2/formz", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Basic Authorization (Deprecated)

Authentication to the API occurs via HTTP Basic Authentication. To authenticate your request, add an Authorization header to the list of request headers where "username:password" is encoded as a Base64 string.

Sample Basic Authorization Header:

Authorization: Basic am9obm55cm9ja2V0QG1haWxlbmF0b3IuY29tOm15cHdk

Sample Request Header for a GET including Authorization header:

GET https://api.goformz.com/v2/formz HTTP/1.1
Host: api.goformz.com
Connection: keep-alive
Authorization: Basic &lt;Base64 encoded(username:password)&gt;
Accept: application/json
Accept-Encoding: gzip, deflate, sdch
Accept-Language: en-US,en;q=0.8

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.