{"_id":"561d4dec57165b0d00aa5d94","parentDoc":null,"project":"55faeacad0e22017005b8265","user":"55fae9d4825d5f19001fa379","category":{"_id":"5601afd381a9670d006d1652","project":"55faeacad0e22017005b8265","version":"55faeacad0e22017005b8268","__v":11,"pages":["5602341e930fe1170074bd22","560235191ba3720d00a6b9a4","561d4dec57165b0d00aa5d94","561d4e369e8e1f0d00983286","561d4e669e8e1f0d00983288","561d4ed26386060d00e06011","561d4f3457165b0d00aa5d97","563108d8f1c0580d00fac6f1","5645082598da41190099f31a","5665cf36e93ae70d00b969f8","56abda994e8ba20d006a23f7"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-22T19:45:23.406Z","from_sync":false,"order":2,"slug":"authentication-guide","title":"Authentication Guide"},"version":{"_id":"55faeacad0e22017005b8268","project":"55faeacad0e22017005b8265","__v":32,"createdAt":"2015-09-17T16:31:06.800Z","releaseDate":"2015-09-17T16:31:06.800Z","categories":["55faeacbd0e22017005b8269","55faf550764f50210095078e","55faf5b5626c341700fd9e96","55faf8a7825d5f19001fa386","560052f91503430d007cc88f","560054f73aa0520d00da0b1a","56005aaf6932a00d00ba7c62","56005c273aa0520d00da0b3f","5601ae7681a9670d006d164d","5601ae926811d00d00ceb487","5601aeb064866b1900f4768d","5601aee850ee460d0002224c","5601afa02499c119000faf19","5601afd381a9670d006d1652","561d4c78281aec0d00eb27b6","561d588d8ca8b90d00210219","563a5f934cc3621900ac278c","5665c5763889610d0008a29e","566710a36819320d000c2e93","56ddf6df8a5ae10e008e3926","56e1c96b2506700e00de6e83","56e1ccc4e416450e00b9e48c","56e1ccdfe63f910e00e59870","56e1cd10bc46be0e002af26a","56e1cd21e416450e00b9e48e","56e3139a51857d0e008e77be","573b4f62ef164e2900a2b881","57c9d1335fd8ca0e006308ed","57e2bd9d1e7b7220000d7fa5","57f2b992ac30911900c7c2b6","58adb5c275df0f1b001ed59b","58c81b5c6dc7140f003c3c46"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"v1","version_clean":"1.0.0","version":"1"},"__v":24,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-13T18:31:08.111Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication Overview\"\n}\n[/block]\nGBDX uses OAuth2 to authenticate users. To make a request to any GBDX API, you'll need an OAuth2 token. This course explains how to get a token, and how to use it to make an API request. \n\n\n## What is OAuth2?\n\nOAuth2 is an open protocol to allow secure authorization  in a simple and standard method from web, mobile, and desktop applications (see __http://oauth.net/__ to learn more about OAuth).\n\n##Definitions\n\n__Term__ | __Definition__\n--- | --- \nAccount/Client |An account or client refers to a customer group and its identifying information. For example, a company using GBDX imagery is a Client. \nUser | Users are associated with accounts/clients. Users have a unique username and password. All users have the same access to data within the account they're associated with.\nAPI Key | An API Key is required for requesting an Oauth token. This is the base64 encoded OAuth2 client_key and client_secret. \nToken|Users will use their account information to request a token. OAuth uses that token to allow the user access to the GDB X API endpoints. \n\n\n\n## Request an Account or User Credentials\n\nTo get a token, you'll need your GBDX username, password, and API key. \n\nIf you have an account, but don't know your API key, you can find it in the web application. See [Lesson: How to Find your API key](doc:lesson-how-to-find-your-api-key-1).\n\nIf you don't have an account, you can create one using the web application. Once you log in to the web app, you can find your API key with your account information.\n\n## Tokens\n Before we get started, there are a few things you should know about tokens.\n\n###__Credentials__\nYou must have your user credentials to request a token. These credentials include:\n\n1. Username\n2. Password\n3. API Key (base64 encoded client key and client secret)\n\n###__Access__\nYour token gives you access to all GBDX API endpoints.\n\n###__Token Expiration__\nTokens have an expiration time of 7 days. If your token expires, you will need to request a new one. \n\n### __Request a Token__\n \nUsing your credentials, you'll send a request to the OAuth Endpoint. See [Get OAuth Token (api-key)](doc:get-oauth-token) \n\nYou will post the following information in the header to make the request:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Url\",\n    \"0-1\": \"https://geobigdata.io/auth/v1/oauth/token/\",\n    \"1-0\": \"Headers\",\n    \"1-1\": \"\\\"Authorization\\\": \\\"Basic \\\" + api_key, \\\"Content-Type\\\": \\\"application/x-www-form-urlencoded\\\"\",\n    \"2-0\": \"Parameters\",\n    \"2-1\": \"\\\"grant_type\\\": \\\"password\\\", \\\"username\\\": username, \\\"password\\\": password\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nIf you are using Python, here is an example token request.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"    import requests\\n    import json\\n\\n    username = \\\"my_user_name\\\"\\n    password = \\\"my_password\\\"\\n    api_key = \\\"my_api_key\\\"\\n\\n    url = 'https://geobigdata.io/auth/v1/oauth/token/'\\n    headers = {\\\"Authorization\\\": \\\"Basic \\\" + api_key, \\\"Content-Type\\\": \\\"application/x-www-form-urlencoded\\\"}\\n    params = {\\\"grant_type\\\": \\\"password\\\", \\\"username\\\": username, \\\"password\\\": password }\\n    results = requests.post(url, headers=headers, data=params)\\n\\n    if results.status_code == 200:\\n        access_token = results.json()['access_token']\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n You can also use Postman to create your request, using the above information. See [Lesson: Postman API Requests](doc:lesson-postman-api-requests)  and the GBDX Open Source [Postman Collection](doc:postman-collection-1) in the Getting Started section, or use the \"try it out\" feature on the [Get OAuth Token (api-key)](doc:get-oauth-token) .\n\n### Response\n\nYour token will look like this:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"access_token\\\": \\\"TOsAVcVbfjT39rCI7S2CohNlUMEv9q\\\",\\n  \\\"token_type\\\": \\\"Bearer\\\",\\n  \\\"expires_in\\\": 604800,\\n  \\\"refresh_token\\\": \\\"9Nbs4XKruXWTnsN5XCuxCEpVyHQmCl\\\",\\n  \\\"scope\\\": \\\"read write\\\"\\n}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n\n\n### __Test your Token__\nBefore you use your token, we recommending testing it to make sure it's valid. See [Test your OAuth Token](doc:test-your-oauth-token) .\n\n### __Use your Token__\nUse Bearer <TOKEN_STRING> in your header to access API endpoints.\nExpected response = 200\n\n### Example\nThis is a Python example of a GET request to \"list all tasks available to the user\", using the token. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" get the tasks using the new access_token, and put it into the headers\\n    url     = 'https://geobigdata.io/workflows/v1/tasks'\\n    headers = {\\\"Authorization\\\": \\\"Bearer \\\" + access_token}\\n    results = requests.get(url,headers=headers)\\n\\n    print results.text\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n      \n\n\n### __Error Codes__\nOAuth returns conventional [HTTP response codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) to indicate success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate a server error. \n\nCommon errors returned by OAuth include:\n\n__Error Code__ | __Issue__ \n--- | --- | --- \n403 | Credentials Denied \n404 | Bad Content","excerpt":"DigitalGlobe's GBDX platform uses OAuth2 for authentication and authorization.","slug":"authentication-course","type":"basic","title":"Authentication Course"}

Authentication Course

DigitalGlobe's GBDX platform uses OAuth2 for authentication and authorization.

[block:api-header] { "type": "basic", "title": "Authentication Overview" } [/block] GBDX uses OAuth2 to authenticate users. To make a request to any GBDX API, you'll need an OAuth2 token. This course explains how to get a token, and how to use it to make an API request. ## What is OAuth2? OAuth2 is an open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications (see __http://oauth.net/__ to learn more about OAuth). ##Definitions __Term__ | __Definition__ --- | --- Account/Client |An account or client refers to a customer group and its identifying information. For example, a company using GBDX imagery is a Client. User | Users are associated with accounts/clients. Users have a unique username and password. All users have the same access to data within the account they're associated with. API Key | An API Key is required for requesting an Oauth token. This is the base64 encoded OAuth2 client_key and client_secret. Token|Users will use their account information to request a token. OAuth uses that token to allow the user access to the GDB X API endpoints. ## Request an Account or User Credentials To get a token, you'll need your GBDX username, password, and API key. If you have an account, but don't know your API key, you can find it in the web application. See [Lesson: How to Find your API key](doc:lesson-how-to-find-your-api-key-1). If you don't have an account, you can create one using the web application. Once you log in to the web app, you can find your API key with your account information. ## Tokens Before we get started, there are a few things you should know about tokens. ###__Credentials__ You must have your user credentials to request a token. These credentials include: 1. Username 2. Password 3. API Key (base64 encoded client key and client secret) ###__Access__ Your token gives you access to all GBDX API endpoints. ###__Token Expiration__ Tokens have an expiration time of 7 days. If your token expires, you will need to request a new one. ### __Request a Token__ Using your credentials, you'll send a request to the OAuth Endpoint. See [Get OAuth Token (api-key)](doc:get-oauth-token) You will post the following information in the header to make the request: [block:parameters] { "data": { "0-0": "Url", "0-1": "https://geobigdata.io/auth/v1/oauth/token/", "1-0": "Headers", "1-1": "\"Authorization\": \"Basic \" + api_key, \"Content-Type\": \"application/x-www-form-urlencoded\"", "2-0": "Parameters", "2-1": "\"grant_type\": \"password\", \"username\": username, \"password\": password" }, "cols": 2, "rows": 3 } [/block] If you are using Python, here is an example token request. [block:code] { "codes": [ { "code": " import requests\n import json\n\n username = \"my_user_name\"\n password = \"my_password\"\n api_key = \"my_api_key\"\n\n url = 'https://geobigdata.io/auth/v1/oauth/token/'\n headers = {\"Authorization\": \"Basic \" + api_key, \"Content-Type\": \"application/x-www-form-urlencoded\"}\n params = {\"grant_type\": \"password\", \"username\": username, \"password\": password }\n results = requests.post(url, headers=headers, data=params)\n\n if results.status_code == 200:\n access_token = results.json()['access_token']", "language": "python" } ] } [/block] You can also use Postman to create your request, using the above information. See [Lesson: Postman API Requests](doc:lesson-postman-api-requests) and the GBDX Open Source [Postman Collection](doc:postman-collection-1) in the Getting Started section, or use the "try it out" feature on the [Get OAuth Token (api-key)](doc:get-oauth-token) . ### Response Your token will look like this: [block:code] { "codes": [ { "code": "{\n \"access_token\": \"TOsAVcVbfjT39rCI7S2CohNlUMEv9q\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 604800,\n \"refresh_token\": \"9Nbs4XKruXWTnsN5XCuxCEpVyHQmCl\",\n \"scope\": \"read write\"\n}", "language": "text" } ] } [/block] ### __Test your Token__ Before you use your token, we recommending testing it to make sure it's valid. See [Test your OAuth Token](doc:test-your-oauth-token) . ### __Use your Token__ Use Bearer <TOKEN_STRING> in your header to access API endpoints. Expected response = 200 ### Example This is a Python example of a GET request to "list all tasks available to the user", using the token. [block:code] { "codes": [ { "code": " get the tasks using the new access_token, and put it into the headers\n url = 'https://geobigdata.io/workflows/v1/tasks'\n headers = {\"Authorization\": \"Bearer \" + access_token}\n results = requests.get(url,headers=headers)\n\n print results.text\n", "language": "python" } ] } [/block] ### __Error Codes__ OAuth returns conventional [HTTP response codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) to indicate success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate a server error. Common errors returned by OAuth include: __Error Code__ | __Issue__ --- | --- | --- 403 | Credentials Denied 404 | Bad Content