{"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}