{"_id":"5a96f950c777af00359e8bd0","project":"55faeacad0e22017005b8265","version":{"_id":"55faeacad0e22017005b8268","project":"55faeacad0e22017005b8265","__v":36,"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","595412446ed4d9001b3e7b37","59e76ce41938310028037295","5a009de510890d001c2aabfe","5a96f89c89442e002041144b"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"v1","version_clean":"1.0.0","version":"1"},"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":6,"slug":"authentication-guide","title":"Authentication Guide"},"user":"55fae9d4825d5f19001fa379","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-02-28T18:47:44.220Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"The new authentication system was deployed on March 22, 2018,\",\n  \"body\": \"All users must get a new token after the deployment.\"\n}\n[/block]\n# Related Documentation\n\n[Authentication Changes Announcement](doc:authentication-changes) \n[Authentication FAQ](doc:authentication-faq) \n[Get a Token](doc:get-a-token) \n[Validate a Token](doc:validate-a-token) \n\n\n# Authentication Overview\nGBDX uses token-based authentication for security.  To get authenticated, a user must request a token, and then must include the token string when submitting an API request. This course explains how to get a token, and how to use it to make an API request. \n\n\n#Definitions\n\n__Term__ | __Definition__\n--- | --- \nAccount |An account refers to a customer group and its identifying information. Accounts can have one or more users. \nUser | Users are associated with accounts. Users have a unique username and password. All users have the same access to data within the account they're associated with.\nToken |A token is a piece of data that includes all the information needed to authenticate a specific user. Users will use their account information to request a token. That token  to allow the user access to the GDBX API endpoints. \n\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. GBDX Username\n2. GBDX Password\n\n## Access\nYour token gives you access to all GBDX API endpoints. It contains all the information needed to authenticate the user. \n\n## Token Expiration\nTokens have an expiration time of 7 days, or 604800 seconds. If your token expires, you will need to request a new one. \n\n## Get a Token\n \nTo request a token, you'll send a request to the following API endpoint:\nhttps://geobigdata.io/auth/v1/oauth/token/\n\nSee [Get a Token](doc:get-a-token) to try it out. \n\nThe following information is required to use a token in an API request:\n\nName | Description\n--- | ---\nUrl | https://geobigdata.io/auth/v1/oauth/token/\nHeaders | \"Authorization\": \"Bearer, \"Content-Type\": \"application/json\". \"application/x-www-form-urlencoded\" is also supported.\nParameters | \"grant_type\": \"password\", \"username\": username, \"password\": password\n\nThe Get a Token request is included in the [Postman Instructions & Collections](doc:postman-instructions-collections) .\n\n### JSON Response \n\nA valid \"Get a Token\" request will return the following response: \n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"access_token\\\": <access token string>\\n    \\\"scope\\\": \\\"read write\\\",\\n    \\\"token_type\\\": \\\"Bearer\\\",\\n    \\\"expires_in\\\": 604800,\\n    \\\"refresh_token\\\": <refresh token string>\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n\n\n## Validate your Token\n\nYou can send a request to validate your token that will return a response with information about your token and account. \n\nThe URL for the Validate Token  `GET` request is: /auth/v1/validate_token\n\nThe response to the Validate Token request is:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n \\t\\\"username\\\": \\\"USERS_NAME(this is typically the email address)\\\",\\n \\t\\\"user_id\\\": \\\"USER_ID\\\",\\n \\t\\\"account_id\\\": \\\"ACCOUNT_ID\\\",\\n \\t\\\"roles\\\": [\\\"ROLE\\\"],\\n \\t\\\"id\\\": \\\"USER_ID\\\",\\n \\t\\\"role\\\": \\\"ROLE\\\",\\n \\t\\\"is_super_user\\\": false,\\n \\t\\\"email\\\": \\\"USER_EMAIL\\\",\\n \\t\\\"account_level\\\": \\\"LEVEL\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nProperty Name | Value | More information\n--- | ---\nusername | GBDX user name | In most cases, the username is the user's email address. A small set of legacy usernames are not email addresses. \nuser_id | GBDX user ID | This is the identification number associated with the user.\naccount_id | GBDX account ID | this is the identification number for the GBDX account the user is associated with.\nroles | List of roles associated with the user | At this time, users can only have one role. \nid | user ID | This field has the same value as the \"user_id\" field for backward compatibility.\nrole | the role associated with the user | This field has the same value as the \"roles\" field. It has been retained for backward compatibility.\nis_super_user | TRUE/FALSE value | This value is set to false unless the user has been granted \"super user\" permissions by GBDX. \nemail | The email address the user entered when signing up for a GBDX account | For most users, the \"username\" and \"email\" fields will have the same value. \naccount_level | GBDX account level | Examples: Basic, Eval\n\n## Error Codes\nThe authentication system 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--- | --- | --- \n\n401 | Unauthorized\n403 | Not authorized for this action\n404 | Bad Content\n\nNote: A 401: unauthorized error means that the user credentials are not valid or it could mean you need to get a token. \n\nIt will frequently mean one of the following:\n\n1. You have not signed the updated GBDX Terms of Service. To accept the new terms, sign into https://gbdx.geobigdata.io . If you have already signed, you won't be prompted. If you're not up to date, you'll be prompted to read and accept the terms. \n\n2. You have not verified your email address. New users receive an email that tells them how to verify their email address. If you didn't sign this, you won't be able to log in or use GBDX services. Contact gbdx-support:::at:::digitalglobe.com if you need assistance. \n\n3. You are not using the correct username or password. Username must be an email address.","excerpt":"This course explains how a user gets authenticated to access and use the GBDX APIs.","slug":"authentication-course","type":"basic","title":"Authentication Course"}

Authentication Course

This course explains how a user gets authenticated to access and use the GBDX APIs.

[block:callout] { "type": "info", "title": "The new authentication system was deployed on March 22, 2018,", "body": "All users must get a new token after the deployment." } [/block] # Related Documentation [Authentication Changes Announcement](doc:authentication-changes) [Authentication FAQ](doc:authentication-faq) [Get a Token](doc:get-a-token) [Validate a Token](doc:validate-a-token) # Authentication Overview GBDX uses token-based authentication for security. To get authenticated, a user must request a token, and then must include the token string when submitting an API request. This course explains how to get a token, and how to use it to make an API request. #Definitions __Term__ | __Definition__ --- | --- Account |An account refers to a customer group and its identifying information. Accounts can have one or more users. User | Users are associated with accounts. Users have a unique username and password. All users have the same access to data within the account they're associated with. Token |A token is a piece of data that includes all the information needed to authenticate a specific user. Users will use their account information to request a token. That token to allow the user access to the GDBX API endpoints. # 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. GBDX Username 2. GBDX Password ## Access Your token gives you access to all GBDX API endpoints. It contains all the information needed to authenticate the user. ## Token Expiration Tokens have an expiration time of 7 days, or 604800 seconds. If your token expires, you will need to request a new one. ## Get a Token To request a token, you'll send a request to the following API endpoint: https://geobigdata.io/auth/v1/oauth/token/ See [Get a Token](doc:get-a-token) to try it out. The following information is required to use a token in an API request: Name | Description --- | --- Url | https://geobigdata.io/auth/v1/oauth/token/ Headers | "Authorization": "Bearer, "Content-Type": "application/json". "application/x-www-form-urlencoded" is also supported. Parameters | "grant_type": "password", "username": username, "password": password The Get a Token request is included in the [Postman Instructions & Collections](doc:postman-instructions-collections) . ### JSON Response A valid "Get a Token" request will return the following response: [block:code] { "codes": [ { "code": "{\n \"access_token\": <access token string>\n \"scope\": \"read write\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 604800,\n \"refresh_token\": <refresh token string>\n}", "language": "json" } ] } [/block] ## Validate your Token You can send a request to validate your token that will return a response with information about your token and account. The URL for the Validate Token `GET` request is: /auth/v1/validate_token The response to the Validate Token request is: [block:code] { "codes": [ { "code": "{\n \t\"username\": \"USERS_NAME(this is typically the email address)\",\n \t\"user_id\": \"USER_ID\",\n \t\"account_id\": \"ACCOUNT_ID\",\n \t\"roles\": [\"ROLE\"],\n \t\"id\": \"USER_ID\",\n \t\"role\": \"ROLE\",\n \t\"is_super_user\": false,\n \t\"email\": \"USER_EMAIL\",\n \t\"account_level\": \"LEVEL\"\n}", "language": "json" } ] } [/block] Property Name | Value | More information --- | --- username | GBDX user name | In most cases, the username is the user's email address. A small set of legacy usernames are not email addresses. user_id | GBDX user ID | This is the identification number associated with the user. account_id | GBDX account ID | this is the identification number for the GBDX account the user is associated with. roles | List of roles associated with the user | At this time, users can only have one role. id | user ID | This field has the same value as the "user_id" field for backward compatibility. role | the role associated with the user | This field has the same value as the "roles" field. It has been retained for backward compatibility. is_super_user | TRUE/FALSE value | This value is set to false unless the user has been granted "super user" permissions by GBDX. email | The email address the user entered when signing up for a GBDX account | For most users, the "username" and "email" fields will have the same value. account_level | GBDX account level | Examples: Basic, Eval ## Error Codes The authentication system 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__ --- | --- | --- 401 | Unauthorized 403 | Not authorized for this action 404 | Bad Content Note: A 401: unauthorized error means that the user credentials are not valid or it could mean you need to get a token. It will frequently mean one of the following: 1. You have not signed the updated GBDX Terms of Service. To accept the new terms, sign into https://gbdx.geobigdata.io . If you have already signed, you won't be prompted. If you're not up to date, you'll be prompted to read and accept the terms. 2. You have not verified your email address. New users receive an email that tells them how to verify their email address. If you didn't sign this, you won't be able to log in or use GBDX services. Contact gbdx-support@digitalglobe.com if you need assistance. 3. You are not using the correct username or password. Username must be an email address.