Home
API Reference

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

Step 2: Get an access token

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 <Base64 encoded(username:password)>
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.