{"_id":"58e566c5b9d1160f002551d2","parentDoc":null,"project":"55843604fd8d910d007b9502","version":{"_id":"558444ceafccfd0d00fcb2bb","forked_from":"55843604fd8d910d007b9505","project":"55843604fd8d910d007b9502","__v":67,"createdAt":"2015-06-19T16:35:26.435Z","releaseDate":"2015-06-19T16:35:26.435Z","categories":["558444cfafccfd0d00fcb2bc","558444cfafccfd0d00fcb2bd","55ad4ce733616a0d00599d2e","55ad4cef6aadf20d0015b764","55ad4cf36aadf20d0015b765","55ad4cfb24cf160d0013584f","55ad4d0024cf160d00135850","55ad4d0a24cf160d00135851","55ad4d0d24cf160d00135852","55ad4d126aadf20d0015b766","55ad4d1624cf160d00135853","55ad4d1933616a0d00599d2f","55ad4d2233616a0d00599d30","55ad4d2e24cf160d00135854","55d35b6bf77e6d0d00b1b092","55d3649a0168850d0073f14a","55d366d40168850d0073f15a","55d37fcff77e6d0d00b1b13f","55d383e50168850d0073f1e1","55d3ac26c336ec0d007c2251","55d3c51cb2330119009c31db","55d3c59bfe37111900e536f3","55d3c5a7fe37111900e536f4","55d3c5b4fe37111900e536f5","55d3c5d4fe37111900e536f6","55d3c5d6b2330119009c31df","55d3c5d71f478b170077c164","55d3c687b2330119009c31e4","55d3c6a4fe37111900e536f9","55d3c6befe37111900e536fa","55d3c6e8d2c66f0d00497f93","55d49dcfd7c16b2d007de905","55d4ca8f5082980d0009c79b","55d4cab9c95a3d2f0069ad3d","55d4d279c95a3d2f0069ad60","55d4d9355082980d0009c7e1","55d4f6b5988e130d000b3eb1","55d64dc8e60a2f0d00b88ecb","5627ca43fcbbc621004ec07d","56c64a0d8f98b50d0012c37c","56f1b8b13eb62a34003ea041","56f1b9df4476fb2200795e8c","57f6907dca5e5d1700039ae9","591dd06ca266c423002ec4ca","59234825e465c11900922518","5936f82eaa591e0027638d57","59972f54fd7078001992c136","599c6da8f180820025f14909","59b054613c3e1b0019cf27d9","59b1ceca2d6231003ad73e5f","59b1cf1857911600382e0dc4","59b1cf2730f3d60010c30ef7","59b1cf385d4b89003035441a","59b1cf5857911600382e0dc6","59bc2c4e26ac9b0010a8b753","59bc2ce20b3eb30010657b70","59f0c793ba3bc90030f413ab","59f0cd62f5ecda00325294b9","59fb55a8e8d0f600101aedc3","59fcb05c067f8d0028613f86","5a2af4a1bc5fba00283909c1","5a83673b0e56010012138c12","5a972f2e77b85a0070e4ebe2","5aa300224ed4b40012c53e1d","5acd20095efd8d000359bb3c","5ad50889c05179000306021e","5af0927a8779670003daff34","5b55a46b282b25000319669e"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3"},"user":"5733479caf2a74190094032a","__v":0,"category":{"_id":"5627ca43fcbbc621004ec07d","project":"55843604fd8d910d007b9502","version":"558444ceafccfd0d00fcb2bb","__v":7,"pages":["5627ca593a4c6b0d00c455e9","5627ca6866c62617009d1844","5627ca823a4c6b0d00c455eb","5627ca9c22ef6a2100fb3513","56292b022c0fd9190067da82","5632ce9310b6040d0087944b","56df6582c0e74f0e00ba6ce6"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-21T17:24:19.325Z","from_sync":false,"order":0,"slug":"api","title":"API"},"githubsync":"","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-04-05T21:51:01.576Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"The Qualtrics API uses a token-based authentication system or OAuth. This guide discusses the token-based authentication system. For information on using OAuth, see [Using OAuth with the Qualtrics APIs](doc:using-oauth).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example\",\n  \"sidebar\": true\n}\n[/block]\nTo authenticate, include your token under the HTTP header **X-API-TOKEN**. The following code examples show how to use token-based authentication.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /API/v3/:collection HTTP/1.1\\nHost: yourdatacenterid.qualtrics.com\\nX-API-TOKEN: yourtokenhere\",\n      \"language\": \"http\",\n      \"name\": null\n    },\n    {\n      \"code\": \"import urllib2 #default module for Python 2.X\\n\\nurl = 'https://yourdatacenter.qualtrics.com/API/v3/:collection'\\nheader = {'X-API-TOKEN': '123456789asdfjklasdflk23253235'} \\n\\nreq = urllib2.Request(url,None,header) #generating the request object\\n\\nhandler = urllib2.urlopen(req) #running the request object\\n\\nprint handler.getcode() #print status code\\nprint handler.headers.getheader('content-type')\",\n      \"language\": \"python\",\n      \"name\": \"Python v2\"\n    },\n    {\n      \"code\": \"import urllib.request #default module for Python 3.X\\n\\nurl = 'https://yourdatacenter.qualtrics.com/API/v3/:collection'\\nheader = {'X-API-TOKEN': '123456789asdfjklasdflk23253235'}\\n\\nreq = urllib.request.Request(url,None,header) #generating the request object\\n\\nhandler = urllib.request.urlopen(req) #running the request object\\n\\nprint(handler.status) #print status code\\nprint(handler.reason)\",\n      \"language\": \"python\",\n      \"name\": \"Python v3\"\n    },\n    {\n      \"code\": \"//this example assumes use of the \\\"request\\\" module\\nvar request = require(\\\"request\\\");\\n\\nvar options = { \\n  method: 'GET',\\n  url: 'https://yourdatacenter.qualtrics.com/API/v3/:collection',\\n  headers: \\n   { \\n     'x-api-token': '123456789asdfjklasdflk23253235'\\n   }\\n};\\n\\nrequest(options, function (error, response, body) {\\n  if (error) throw new Error(error);\\n  console.log(body);\\n  // run some code\\n});\\n\",\n      \"language\": \"javascript\",\n      \"name\": \"Node.js\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How to Find Your Token\"\n}\n[/block]\n1. Login to Qualtrics\n2. Go to Account Settings in the user dropdown\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/x6lgSP3oSFG03uq4bxB1_accounSettigns.png\",\n        \"accounSettigns.png\",\n        \"1017\",\n        \"250\",\n        \"#047bc3\",\n        \"\"\n      ],\n      \"caption\": \"User Dropdown\",\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n3. Go to Qualtrics IDs\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/npJ68D7gQbyE8K4e3gZo_ExampleQualtricsIds_highlight.png\",\n        \"ExampleQualtricsIds_highlight.png\",\n        \"1226\",\n        \"493\",\n        \"#057bc4\",\n        \"\"\n      ],\n      \"sizing\": \"full\",\n      \"caption\": \"Qualtrics IDs\"\n    }\n  ]\n}\n[/block]\n4. Click Generate if you haven't generated your token yet\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Generate Token\",\n  \"body\": \"If you already have an API token, **Generate Token** will replace it with a new one. Any existing API calls will not work until they are updated to use the new token.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Protecting Your API Token\"\n}\n[/block]\nBecause the API token allows access to the its owner's resources, anyone who has the token can gain access and modify or delete information. The API token should be treated as confidential and protected from unauthorized exposure. Here are some best practices for protecting your API token:\n\n- Do not hardcode the API token into source code that is checked into a repository. Anyone who has access to the code has access to the token. Obtain the token from an environment variable or a source file that is not checked into the project.\n- Develop a plan for distributing a new token should the old one become public. You can easily generate a new token in the administrator user interface (see step 4 in the previous section), but all existing software that uses the old token will stop working. You will need to distribute the new token securely.\n- Scrub all code before it is released to the public to make sure no hardcoded API tokens exist.\n- Be wary of client-side code that uses tokens. It is very easy to obtain the token from the code or binary because you cannot control access (as with server-based code). \n- Make sure the certificate chain does not include trusted self-signed certificates or certificates that were not signed by trusted root certification authorities. Users can set up a decrypting proxy that will sniff SSL traffic and obtain the token.","excerpt":"","slug":"authentication","type":"basic","title":"Authentication"}
The Qualtrics API uses a token-based authentication system or OAuth. This guide discusses the token-based authentication system. For information on using OAuth, see [Using OAuth with the Qualtrics APIs](doc:using-oauth). [block:api-header] { "type": "basic", "title": "Example", "sidebar": true } [/block] To authenticate, include your token under the HTTP header **X-API-TOKEN**. The following code examples show how to use token-based authentication. [block:code] { "codes": [ { "code": "GET /API/v3/:collection HTTP/1.1\nHost: yourdatacenterid.qualtrics.com\nX-API-TOKEN: yourtokenhere", "language": "http", "name": null }, { "code": "import urllib2 #default module for Python 2.X\n\nurl = 'https://yourdatacenter.qualtrics.com/API/v3/:collection'\nheader = {'X-API-TOKEN': '123456789asdfjklasdflk23253235'} \n\nreq = urllib2.Request(url,None,header) #generating the request object\n\nhandler = urllib2.urlopen(req) #running the request object\n\nprint handler.getcode() #print status code\nprint handler.headers.getheader('content-type')", "language": "python", "name": "Python v2" }, { "code": "import urllib.request #default module for Python 3.X\n\nurl = 'https://yourdatacenter.qualtrics.com/API/v3/:collection'\nheader = {'X-API-TOKEN': '123456789asdfjklasdflk23253235'}\n\nreq = urllib.request.Request(url,None,header) #generating the request object\n\nhandler = urllib.request.urlopen(req) #running the request object\n\nprint(handler.status) #print status code\nprint(handler.reason)", "language": "python", "name": "Python v3" }, { "code": "//this example assumes use of the \"request\" module\nvar request = require(\"request\");\n\nvar options = { \n method: 'GET',\n url: 'https://yourdatacenter.qualtrics.com/API/v3/:collection',\n headers: \n { \n 'x-api-token': '123456789asdfjklasdflk23253235'\n }\n};\n\nrequest(options, function (error, response, body) {\n if (error) throw new Error(error);\n console.log(body);\n // run some code\n});\n", "language": "javascript", "name": "Node.js" } ], "sidebar": true } [/block] [block:api-header] { "type": "basic", "title": "How to Find Your Token" } [/block] 1. Login to Qualtrics 2. Go to Account Settings in the user dropdown [block:image] { "images": [ { "image": [ "https://files.readme.io/x6lgSP3oSFG03uq4bxB1_accounSettigns.png", "accounSettigns.png", "1017", "250", "#047bc3", "" ], "caption": "User Dropdown", "sizing": "full" } ] } [/block] 3. Go to Qualtrics IDs [block:image] { "images": [ { "image": [ "https://files.readme.io/npJ68D7gQbyE8K4e3gZo_ExampleQualtricsIds_highlight.png", "ExampleQualtricsIds_highlight.png", "1226", "493", "#057bc4", "" ], "sizing": "full", "caption": "Qualtrics IDs" } ] } [/block] 4. Click Generate if you haven't generated your token yet [block:callout] { "type": "danger", "title": "Generate Token", "body": "If you already have an API token, **Generate Token** will replace it with a new one. Any existing API calls will not work until they are updated to use the new token." } [/block] [block:api-header] { "title": "Protecting Your API Token" } [/block] Because the API token allows access to the its owner's resources, anyone who has the token can gain access and modify or delete information. The API token should be treated as confidential and protected from unauthorized exposure. Here are some best practices for protecting your API token: - Do not hardcode the API token into source code that is checked into a repository. Anyone who has access to the code has access to the token. Obtain the token from an environment variable or a source file that is not checked into the project. - Develop a plan for distributing a new token should the old one become public. You can easily generate a new token in the administrator user interface (see step 4 in the previous section), but all existing software that uses the old token will stop working. You will need to distribute the new token securely. - Scrub all code before it is released to the public to make sure no hardcoded API tokens exist. - Be wary of client-side code that uses tokens. It is very easy to obtain the token from the code or binary because you cannot control access (as with server-based code). - Make sure the certificate chain does not include trusted self-signed certificates or certificates that were not signed by trusted root certification authorities. Users can set up a decrypting proxy that will sniff SSL traffic and obtain the token.