{"_id":"57fcc4870312b20e00ac64f1","category":{"_id":"57fcc4860312b20e00ac64c7","__v":0,"version":"57fcc4860312b20e00ac64c0","project":"5435687035740020002a1c04","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-11-25T22:05:12.981Z","from_sync":false,"order":6,"slug":"agent-integration","title":"Data Agent"},"parentDoc":null,"__v":1,"version":{"_id":"57fcc4860312b20e00ac64c0","project":"5435687035740020002a1c04","__v":1,"createdAt":"2016-10-11T10:52:54.637Z","releaseDate":"2016-10-11T10:52:54.637Z","categories":["57fcc4860312b20e00ac64c1","57fcc4860312b20e00ac64c2","57fcc4860312b20e00ac64c3","57fcc4860312b20e00ac64c4","57fcc4860312b20e00ac64c5","57fcc4860312b20e00ac64c6","57fcc4860312b20e00ac64c7","57fcc4860312b20e00ac64c8","57fcc4860312b20e00ac64c9","57fcc4860312b20e00ac64ca","57fcc4860312b20e00ac64cb"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"[APP-1265], [APP-1035]","version_clean":"5.2.0","version":"5.2"},"project":"5435687035740020002a1c04","user":"5589fde775eaf50d004e4b0c","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-07T23:07:54.447Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":10,"body":"Some third party APIs will require authentication via [oAuth](http://oauth.net/). The TelemetryTV Agent is designed to connect with and store the credentials for oAuth version 1.0, 1.0a, and 2.0 services. This section will demonstrate the authentication process for an oAuth v2.0 service (Salesforce) and v1.0 (Quickbooks).\n\n## Authenticating with oAuth v2.0\n\noAuth 2.0 services will provide callback URLs within their documentation to be used for authorization and token requests. For our Salesforce example this documentation can be found [here](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_understanding_oauth_endpoints.htm). These URLs must be added to the [Agent configuration file](doc:agent-configuration-file) along with an ID (key) and secret (password). These are attained when [creating an oAuth connected app](https://help.salesforce.com/apex/HTViewHelpDoc?id=connected_app_create.htm).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[oauth.salesforce_api]\\nversion = 2\\nclient_id = \\\"6MGG91fhikjGaMd9Z3YfLP7tKEgvMqRzJv4OdIKXF_8y8MblTj9p.f_Gd4Gg5TV.5_E_RIydapHSmPMtfHwXf\\\"\\nclient_secret = \\\"5386741059674020496\\\"\\nauthorization_url = \\\"https://login.salesforce.com/services/oauth2/authorize\\\"\\ntoken_url = \\\"https://login.salesforce.com/services/oauth2/token\\\"\\nscopes = [\\\"\\\"]\",\n      \"language\": \"toml\"\n    }\n  ]\n}\n[/block]\nAfter a config entry has been created you can execute the Agent with the `oauth-request` command along with the `--name` flag referencing the oAuth entry name.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"./gotelemetry_agent -c config.toml oauth-request -n salesforce_api\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/gxA8XoFkSHSZNWo59iC2_oauth2_request.png\",\n        \"oauth2_request.png\",\n        \"1170\",\n        \"902\",\n        \"#396e9a\",\n        \"\"\n      ],\n      \"caption\": \"\"\n    }\n  ]\n}\n[/block]\nExecuting the request will return a URL to be copied and pasted into your web browser's address bar. You will be prompted to sign in to the third party service and allow the TelemetryTV Agent to access your data.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0gCVRYczS2eqwuJJ8BUs_oauth2_handshake.png\",\n        \"oauth2_handshake.png\",\n        \"2880\",\n        \"1800\",\n        \"#65b668\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nAfter granting permissions to TelemetryTV you will be forwarded to a page containing your oAuth response code. Copy this code and use it to execute the Agent with the `oauth-exchange` command. You must provide the response code using the `--code` flag, and specify the entry name with the `--name` flag.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"./gotelemetry_agent -c config.toml oauth-exchange -n salesforce_api -o [code]\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/tZsvInW8TNOAKyslTtoT_oauth2_exchange.png\",\n        \"oauth2_exchange.png\",\n        \"1170\",\n        \"902\",\n        \"#3c6f9a\",\n        \"\"\n      ],\n      \"caption\": \"\"\n    }\n  ]\n}\n[/block]\nAfter executing the `oauth-exchange` you will receive a prompt noting that you can now make [third party API calls](doc:accessing-third-party-apis-from-lua) using the entry.\n\n## Authenticating with oAuth v1.0\n\noAuth 1.0 authentication with the Agent is very similar to oAuth v2.0. You will need to provide a credentials URL in addition to the authorization and access token endpoints. For Quickbooks this can be found [here](https://developer.intuit.com/docs/0100_accounting/0060_authentication_and_authorization/connect_from_within_your_app).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[oauth.quickbooks_api]\\nversion = 1\\nclient_id = \\\"qyprd35o8wyN1FWsJaqGj34hQTe5Dk\\\"\\nclient_secret = \\\"tgaEug8GLfvhyu5ExGSheT4m65FN8Uy6C23E5tN2\\\"\\nauthorization_url = \\\"https://appcenter.intuit.com/Connect/Begin\\\"\\ncredentials_url = \\\"https://oauth.intuit.com/oauth/v1/get_request_token\\\"\\ntoken_url = \\\"https://oauth.intuit.com/oauth/v1/get_access_token\\\"\",\n      \"language\": \"toml\"\n    }\n  ]\n}\n[/block]\nThe `oauth-request` command works the same way requiring a `--name` flag noting the oAuth entry.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"./gotelemetry_agent -c config.toml oauth-request -n quickbooks_api\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Oo9vn10rT5KK5sp92ibA_oauth1_request.png\",\n        \"oauth1_request.png\",\n        \"1170\",\n        \"902\",\n        \"#3b6f9a\",\n        \"\"\n      ],\n      \"caption\": \"\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/sHXVA3StTcKTdxXnNSIf_oauth1_handshake.png\",\n        \"oauth1_handshake.png\",\n        \"2880\",\n        \"1800\",\n        \"#5cb4a4\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nAdditional parameters are required when running `oauth-exchange` using oAuth v1.0. In addition to the `--code` you must also provide values for the `--verifier` and `--realm` flags.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"./gotelemetry_agent -c config.toml oauth-exchange -n quickbooks_api -o [code] -e [verifier] -r [realm]\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/wBwIWcj4S86I7yHMccxl_oauth1_exchange.png\",\n        \"oauth1_exchange.png\",\n        \"1170\",\n        \"902\",\n        \"#3c6f98\",\n        \"\"\n      ],\n      \"caption\": \"\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"oauth","type":"basic","title":"oAuth"}
Some third party APIs will require authentication via [oAuth](http://oauth.net/). The TelemetryTV Agent is designed to connect with and store the credentials for oAuth version 1.0, 1.0a, and 2.0 services. This section will demonstrate the authentication process for an oAuth v2.0 service (Salesforce) and v1.0 (Quickbooks). ## Authenticating with oAuth v2.0 oAuth 2.0 services will provide callback URLs within their documentation to be used for authorization and token requests. For our Salesforce example this documentation can be found [here](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_understanding_oauth_endpoints.htm). These URLs must be added to the [Agent configuration file](doc:agent-configuration-file) along with an ID (key) and secret (password). These are attained when [creating an oAuth connected app](https://help.salesforce.com/apex/HTViewHelpDoc?id=connected_app_create.htm). [block:code] { "codes": [ { "code": "[oauth.salesforce_api]\nversion = 2\nclient_id = \"6MGG91fhikjGaMd9Z3YfLP7tKEgvMqRzJv4OdIKXF_8y8MblTj9p.f_Gd4Gg5TV.5_E_RIydapHSmPMtfHwXf\"\nclient_secret = \"5386741059674020496\"\nauthorization_url = \"https://login.salesforce.com/services/oauth2/authorize\"\ntoken_url = \"https://login.salesforce.com/services/oauth2/token\"\nscopes = [\"\"]", "language": "toml" } ] } [/block] After a config entry has been created you can execute the Agent with the `oauth-request` command along with the `--name` flag referencing the oAuth entry name. [block:code] { "codes": [ { "code": "./gotelemetry_agent -c config.toml oauth-request -n salesforce_api", "language": "shell" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/gxA8XoFkSHSZNWo59iC2_oauth2_request.png", "oauth2_request.png", "1170", "902", "#396e9a", "" ], "caption": "" } ] } [/block] Executing the request will return a URL to be copied and pasted into your web browser's address bar. You will be prompted to sign in to the third party service and allow the TelemetryTV Agent to access your data. [block:image] { "images": [ { "image": [ "https://files.readme.io/0gCVRYczS2eqwuJJ8BUs_oauth2_handshake.png", "oauth2_handshake.png", "2880", "1800", "#65b668", "" ] } ] } [/block] After granting permissions to TelemetryTV you will be forwarded to a page containing your oAuth response code. Copy this code and use it to execute the Agent with the `oauth-exchange` command. You must provide the response code using the `--code` flag, and specify the entry name with the `--name` flag. [block:code] { "codes": [ { "code": "./gotelemetry_agent -c config.toml oauth-exchange -n salesforce_api -o [code]", "language": "shell" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/tZsvInW8TNOAKyslTtoT_oauth2_exchange.png", "oauth2_exchange.png", "1170", "902", "#3c6f9a", "" ], "caption": "" } ] } [/block] After executing the `oauth-exchange` you will receive a prompt noting that you can now make [third party API calls](doc:accessing-third-party-apis-from-lua) using the entry. ## Authenticating with oAuth v1.0 oAuth 1.0 authentication with the Agent is very similar to oAuth v2.0. You will need to provide a credentials URL in addition to the authorization and access token endpoints. For Quickbooks this can be found [here](https://developer.intuit.com/docs/0100_accounting/0060_authentication_and_authorization/connect_from_within_your_app). [block:code] { "codes": [ { "code": "[oauth.quickbooks_api]\nversion = 1\nclient_id = \"qyprd35o8wyN1FWsJaqGj34hQTe5Dk\"\nclient_secret = \"tgaEug8GLfvhyu5ExGSheT4m65FN8Uy6C23E5tN2\"\nauthorization_url = \"https://appcenter.intuit.com/Connect/Begin\"\ncredentials_url = \"https://oauth.intuit.com/oauth/v1/get_request_token\"\ntoken_url = \"https://oauth.intuit.com/oauth/v1/get_access_token\"", "language": "toml" } ] } [/block] The `oauth-request` command works the same way requiring a `--name` flag noting the oAuth entry. [block:code] { "codes": [ { "code": "./gotelemetry_agent -c config.toml oauth-request -n quickbooks_api", "language": "shell" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/Oo9vn10rT5KK5sp92ibA_oauth1_request.png", "oauth1_request.png", "1170", "902", "#3b6f9a", "" ], "caption": "" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/sHXVA3StTcKTdxXnNSIf_oauth1_handshake.png", "oauth1_handshake.png", "2880", "1800", "#5cb4a4", "" ] } ] } [/block] Additional parameters are required when running `oauth-exchange` using oAuth v1.0. In addition to the `--code` you must also provide values for the `--verifier` and `--realm` flags. [block:code] { "codes": [ { "code": "./gotelemetry_agent -c config.toml oauth-exchange -n quickbooks_api -o [code] -e [verifier] -r [realm]", "language": "shell" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/wBwIWcj4S86I7yHMccxl_oauth1_exchange.png", "oauth1_exchange.png", "1170", "902", "#3c6f98", "" ], "caption": "" } ] } [/block]