{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[]},"settings":""},"next":{"description":"","pages":[]},"title":"Authentication","type":"basic","slug":"authentication","excerpt":"","body":"[block:api-header]\n{\n  \"title\": \"Token Authentication (Preferred)\"\n}\n[/block]\nAuthentication 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. \n\nTo achieve this authentication, you must follow a 3-step process:\n\n\n## ****Step 1****: Setup your API Credentials\n\n  * Go to the [Settings](https://app.goformz.com/settings) page in your GoFormz account, and click on [API Credentials](https://app.goformz.com/apicredentials).\n  * 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.\n  * Make sure to copy your Client Secret, as it will not be available again.  However, you can regenerate a new one.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ac0d0a6-settings.png\",\n        \"settings.png\",\n        1627,\n        818,\n        \"#f5f6f7\"\n      ],\n      \"border\": true,\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\n## Step 2: Get an access token\n\n  * Make a POST request to [https://accounts.goformz.com/connect/token](https://accounts.goformz.com/connect/token) with your Client ID and Secret obtained from Step 1.\n  * As shown in the examples below, you will need to include a *scope *and *grant_type*.\n\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /connect/token HTTP/1.1\\nHost: https://accounts.goformz.com\\nContent-Type: application/x-www-form-urlencoded\\nscope=public_api&grant_type=client_credentials&client_id={Client Id}&client_secret={Client Secret}\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"curl --location --request POST 'https://accounts.goformz.com/connect/token' \\\\\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\\\\n--data-urlencode 'scope=public_api' \\\\\\n--data-urlencode 'grant_type=client_credentials' \\\\\\n--data-urlencode 'client_id={Client Id}' \\\\\\n--data-urlencode 'client_secret={Client Secret}'\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"var myHeaders = new Headers();\\nmyHeaders.append(\\\"Content-Type\\\", \\\"application/x-www-form-urlencoded\\\");\\n\\nvar urlencoded = new URLSearchParams();\\nurlencoded.append(\\\"scope\\\", \\\"public_api\\\");\\nurlencoded.append(\\\"grant_type\\\", \\\"client_credentials\\\");\\nurlencoded.append(\\\"client_id\\\", \\\"{Client Id}\\\");\\nurlencoded.append(\\\"client_secret\\\", \\\"{Client Secret}\\\");\\n\\nvar requestOptions = {\\n  method: 'POST',\\n  headers: myHeaders,\\n  body: urlencoded,\\n  redirect: 'follow'\\n};\\n\\nfetch(\\\"https://accounts.goformz.com/connect/token\\\", requestOptions)\\n  .then(response => response.text())\\n  .then(result => console.log(result))\\n  .catch(error => console.log('error', error));\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Access Token Lifetime\",\n  \"body\": \"* Our access tokens will expire in 3600 seconds (1 hour).\\n  * To avoid performance and throttling issues, it is recommended to only get a new access \\n     token once your existing token is expired, or nearly expired.\\n  * An expired access token will result in an Unauthorized request.\"\n}\n[/block]\n\n\n## Step 3: How to use your access token\n\n  * Use the Bearer Authorization header, as shown in the examples below.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /v2/formz HTTP/1.1\\nHost: api.goformz.com\\nAuthorization: Bearer {access_token}\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"curl --location --request GET 'https://api.goformz.com/v2/formz' \\\\\\n--header 'Authorization: Bearer {access_token}'\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"var myHeaders = new Headers();\\nmyHeaders.append(\\\"Authorization\\\", \\\"Bearer {access_token}\\\");\\n\\nvar requestOptions = {\\n  method: 'GET',\\n  headers: myHeaders,\\n  redirect: 'follow'\\n};\\n\\nfetch(\\\"https://api.goformz.com/v2/formz\\\", requestOptions)\\n  .then(response => response.text())\\n  .then(result => console.log(result))\\n  .catch(error => console.log('error', error));\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Basic Authorization (Deprecated)\"\n}\n[/block]\nAuthentication 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.\n\nSample Basic Authorization Header:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Authorization: Basic am9obm55cm9ja2V0QG1haWxlbmF0b3IuY29tOm15cHdk\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nSample Request Header for a GET including Authorization header:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET https://api.goformz.com/v2/formz HTTP/1.1\\nHost: api.goformz.com\\nConnection: keep-alive\\nAuthorization: Basic <Base64 encoded(username:password)>\\nAccept: application/json\\nAccept-Encoding: gzip, deflate, sdch\\nAccept-Language: en-US,en;q=0.8\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nAll API requests must be made over `HTTPS`. Calls made over plain `HTTP` will fail. You must authenticate for all requests.","updates":[],"order":1,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"553591ce63cc650d0031292f","createdAt":"2015-04-20T23:46:00.826Z","githubsync":"","project":"55357364e02d480d0003c6d3","category":{"sync":{"isSync":false,"url":""},"pages":["553591ce63cc650d00312929","553591ce63cc650d0031292a","553591ce63cc650d0031292b","553591ce63cc650d0031292c","553591ce63cc650d0031292d","553591ce63cc650d0031292e","553591ce63cc650d0031292f","553591ce63cc650d00312930"],"title":"API","slug":"api","order":0,"from_sync":false,"reference":false,"_id":"553591cd63cc650d00312926","__v":1,"createdAt":"2015-04-20T21:45:09.762Z","project":"55357364e02d480d0003c6d3","version":"553591cd63cc650d00312925"},"__v":5,"version":{"version":"2","version_clean":"2.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["553591cd63cc650d00312926","553591cd63cc650d00312927","5536e4d39f7f2d0d00b1cd54","5536e55c20d5ca0d0001580a","5536e6bf7fe60f0d000fd1c0","5536f5bba171250d00c00556","553a974369c2630d00a8562e","553a97c60074c80d00621c2a","553a98332af5f20d000fc32a","553a9b9869c2630d00a85642","556e0f23d02e0b190042f13d","563249b1dcc27a1700823650","5639113f049e420d00476b03","59a5dd94aaa11d003334edb4"],"_id":"553591cd63cc650d00312925","project":"55357364e02d480d0003c6d3","releaseDate":"2015-04-20T23:54:53.134Z","__v":13,"forked_from":"55357365e02d480d0003c6d6","createdAt":"2015-04-20T23:54:53.134Z"},"user":"55356ede6040a20d00454508","parentDoc":null}

API

Formz

Templates

Groups

Users

Files

Queue

Data Sources

Form Fields

Webhooks

Authentication

[block:api-header] { "title": "Token Authentication (Preferred)" } [/block] 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](https://app.goformz.com/settings) page in your GoFormz account, and click on [API Credentials](https://app.goformz.com/apicredentials). * 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. [block:image] { "images": [ { "image": [ "https://files.readme.io/ac0d0a6-settings.png", "settings.png", 1627, 818, "#f5f6f7" ], "border": true, "sizing": "80" } ] } [/block] ## Step 2: Get an access token * Make a POST request to [https://accounts.goformz.com/connect/token](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*. [block:code] { "codes": [ { "code": "POST /connect/token HTTP/1.1\nHost: https://accounts.goformz.com\nContent-Type: application/x-www-form-urlencoded\nscope=public_api&grant_type=client_credentials&client_id={Client Id}&client_secret={Client Secret}", "language": "http" }, { "code": "curl --location --request POST 'https://accounts.goformz.com/connect/token' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--data-urlencode 'scope=public_api' \\\n--data-urlencode 'grant_type=client_credentials' \\\n--data-urlencode 'client_id={Client Id}' \\\n--data-urlencode 'client_secret={Client Secret}'", "language": "curl" }, { "code": "var myHeaders = new Headers();\nmyHeaders.append(\"Content-Type\", \"application/x-www-form-urlencoded\");\n\nvar urlencoded = new URLSearchParams();\nurlencoded.append(\"scope\", \"public_api\");\nurlencoded.append(\"grant_type\", \"client_credentials\");\nurlencoded.append(\"client_id\", \"{Client Id}\");\nurlencoded.append(\"client_secret\", \"{Client Secret}\");\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: urlencoded,\n redirect: 'follow'\n};\n\nfetch(\"https://accounts.goformz.com/connect/token\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));", "language": "javascript" } ] } [/block] [block:callout] { "type": "info", "title": "Access Token Lifetime", "body": "* Our access tokens will expire in 3600 seconds (1 hour).\n * To avoid performance and throttling issues, it is recommended to only get a new access \n token once your existing token is expired, or nearly expired.\n * An expired access token will result in an Unauthorized request." } [/block] ## Step 3: How to use your access token * Use the Bearer Authorization header, as shown in the examples below. [block:code] { "codes": [ { "code": "GET /v2/formz HTTP/1.1\nHost: api.goformz.com\nAuthorization: Bearer {access_token}", "language": "http" }, { "code": "curl --location --request GET 'https://api.goformz.com/v2/formz' \\\n--header 'Authorization: Bearer {access_token}'", "language": "curl" }, { "code": "var myHeaders = new Headers();\nmyHeaders.append(\"Authorization\", \"Bearer {access_token}\");\n\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://api.goformz.com/v2/formz\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));", "language": "javascript" } ] } [/block] [block:api-header] { "title": "Basic Authorization (Deprecated)" } [/block] 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: [block:code] { "codes": [ { "code": "Authorization: Basic am9obm55cm9ja2V0QG1haWxlbmF0b3IuY29tOm15cHdk", "language": "text" } ] } [/block] Sample Request Header for a GET including Authorization header: [block:code] { "codes": [ { "code": "GET https://api.goformz.com/v2/formz HTTP/1.1\nHost: api.goformz.com\nConnection: keep-alive\nAuthorization: Basic <Base64 encoded(username:password)>\nAccept: application/json\nAccept-Encoding: gzip, deflate, sdch\nAccept-Language: en-US,en;q=0.8", "language": "http" } ] } [/block] All API requests must be made over `HTTPS`. Calls made over plain `HTTP` will fail. You must authenticate for all requests.