Token Authentication (Preferred)

GoFormz API uses standard OAuth 2 specifications. This process includes obtaining an encrypted and signed JWT token from our server. This is then used to validate a user's identity, in place of a username and password.

📘
Access Token Lifetime

Access tokens will expire in 3600 seconds (1 hour).

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

An expired access token will result in an "Unauthorized request".

In the web app, navigate to the Settings tab and click API Access. Then, follow the steps below.

Copy your Client Secret.

Note: Make sure to copy your Client Secret, as it will not be available again.
But - if necessary - you can regenerate a new one.
Make a POST request to https://accounts.goformz.com/connect/token with your Client ID and Client Secret.

You'll need to include a scope and grant_type - you'll find examples of this below.

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

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.