{"__v":4,"_id":"55369f1f6fd3c40d00334978","api":{"auth":"required","params":[],"results":{"codes":[]},"settings":"","url":""},"body":"Exversion has two authentication methods: one for reading data from repositories you have permission to access and one for both creating and writing to data repositories.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API Keys: Fetching and Reading Data\"\n}\n[/block]\nExversion generates this API key automatically when you create an account. It will allow you read only access to both datasets you own, public datasets hosted on Exversion and private datasets you have been given access to. If your key gets stolen it can easily be regenerated.\n\nTo retrieve your key make sure you are logged in to your account and [open up your settings](https://exversion.com/account/settings/).\n\nExample Request:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import requests\\n\\nr = requests.get(\\\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR KEY]&_limit=[NUMBER OF ROWS]\\\")\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"<?php\\n\\tch = curl_init();\\n\\tcurl_setopt($ch, CURLOPT_HEADER, 0);\\n\\tcurl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);\\n\\tcurl_setopt($ch, CURLOPT_CONNECTTIMEOUT,20);\\n\\tcurl_setopt($ch, CURLOPT_URL, \\\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR KEY]&_limit=[NUMBER OF ROWS]\\\");\\n\\t$result = json_decode(curl_exec($ch));\\n\\tcurl_close($ch);\\n?>\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"require 'unirest'\\n\\nresponse = Unirest.get(\\\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR KEY]&_limit=[NUMBER OF ROWS]\\\")\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\nExample Response:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"status\\\":200,\\n \\\"message\\\":\\\"Success\\\",\\n \\\"body\\\":[\\n  \\t{\\n  \\t\\t\\\"_id\\\":\\\"FSBEQAKJQJH059881.299319683364711375720224963\\\",\\n  \\t\\t\\\"lobbyist_first_name\\\":\\\"James\\\",\\n  \\t\\t\\\"lobbyist_last_name\\\":\\\"Connolly\\\",\\n  \\t\\t\\\"filing_year\\\":\\\"2012\\\"\\n\\t\\t},\\n\\t\\t{\\n    \\t\\\"_id\\\":\\\"FSBEQAKJQJH059857.653845592045361375720225585\\\",\\n    \\t\\\"lobbyist_first_name\\\":\\\"James\\\",\\n    \\t\\\"lobbyist_last_name\\\":\\\"Gilliam\\\",\\n    \\t\\\"filing_year\\\":\\\"2012\\\"\\n  \\t},\\n\\t\\t{\\n  \\t\\t\\\"_id\\\":\\\"FSBEQAKJQJH05984.6746827350097781375720228202\\\",\\n  \\t\\t\\\"lobbyist_first_name\\\":\\\"James\\\",\\n  \\t\\t\\\"lobbyist_last_name\\\":\\\"Alexander\\\",\\n  \\t\\t\\\"filing_year\\\":\\\"2012\\\"\\n\\t\\t},\\n\\t\\t{\\n \\t\\t\\t\\\"_id\\\":\\\"FSBEQAKJQJH059878.41251410109141375720234876\\\",\\n  \\t\\t\\\"lobbyist_first_name\\\":\\\"James\\\",\\n  \\t\\t\\\"lobbyist_last_name\\\":\\\"Banks\\\",\\n  \\t\\t\\\"filing_year\\\":\\\"2012\\\"\\n\\t\\t},\\n\\t\\t{\\n  \\t\\t\\\"_id\\\":\\\"FSBEQAKJQJH059890.543216294539121375720235255\\\",\\n  \\t\\t\\\"lobbyist_first_name\\\":\\\"James\\\",\\n  \\t\\t\\\"lobbyist_last_name\\\":\\\"Darnell\\\",\\n  \\t\\t\\\"filing_year\\\":\\\"2012\\\"\\n\\t\\t},\\n\\t\\t{\\n    \\t\\\"_id\\\":\\\"FSBEQAKJQJH059884.74339911080541375720244224\\\",\\n    \\t\\\"lobbyist_first_name\\\":\\\"James\\\",\\n    \\t\\\"lobbyist_last_name\\\":\\\"Henn\\\",\\n    \\t\\\"filing_year\\\":\\\"2012\\\"\\n  \\t},\\n\\t]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"OAuth Access Token: Creating, Deleting and Editing Datasets\"\n}\n[/block]\nGaining write access to data hosted on Exversion requires a more secure from of authentication. Exversion supports OAuth, issuing access tokens that do not expire but can be revoked. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"But I Just Want Access to My Own Account!\",\n  \"body\": \"It's annoying when you want to write scripts that will only ever try to access your account and you have to waste time and energy building a completely unnecessary OAuth client just to generate and fetch the access token. We hate that, so we built in an [OAuth client into Exversion's web interface](https://exversion.com/oauth/remote/) that will generate the token for you.\\n\\nThis token is just for personal use. If you plan on building an application that other people will use to manipulate their accounts, you will have to support OAuth.\"\n}\n[/block]\nThe first step in generating an access token is [registering your application with Exversion](https://exversion.com/oauth/create/). This will generate a Client ID and Secret for your application to use.\n\nTo start the authorization process is to send a request to the following URL:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://www.exversion.com/oauth/v2/auth?client_id=[CLIENT ID]&response_type=code&redirect_uri=[REDIRECT URL]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nIf the client id matches a valid Exversion App the user will be redirected to a page asking them to allow or deny your app. Once they click ALLOW they are redirected back to your app via the redirect url specified when you registered your app.\n\nA code will be appended to the redirect url like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://www.example.com/?code=[CODE HERE]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nOnce you have the code, you can generate the access_token by sending the following request back to Exversion\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://www.exversion.com/oauth/v2/token?client_id=[CLIENT ID]&client_secret=[CLIENT SECRET]&grant_type=authorization_code&redirect_uri=[REDIRECT URL]&code=[CODE HERE]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nThe response from Exversion will look like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"access_token\\\": \\\"8315796acc79f6a1bfb4e4935aea01362d59ecce\\\",\\n  \\\"token_type\\\": \\\"bearer\\\",\\n  \\\"scope\\\": null,\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nInclude the access token as part of any requests that create, edit or delete information from Exversion.","category":"542ac32254d88d140075fc3a","createdAt":"2015-04-21T19:03:59.993Z","excerpt":"making sure the API knows who the f you are","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"542ac32254d88d140075fc36","slug":"authentication","sync_unique":"","title":"Authentication","type":"basic","updates":[],"user":"542ac2d054d88d140075fc29","version":"542ac32254d88d140075fc39"}

Authentication

making sure the API knows who the f you are

Exversion has two authentication methods: one for reading data from repositories you have permission to access and one for both creating and writing to data repositories. [block:api-header] { "type": "basic", "title": "API Keys: Fetching and Reading Data" } [/block] Exversion generates this API key automatically when you create an account. It will allow you read only access to both datasets you own, public datasets hosted on Exversion and private datasets you have been given access to. If your key gets stolen it can easily be regenerated. To retrieve your key make sure you are logged in to your account and [open up your settings](https://exversion.com/account/settings/). Example Request: [block:code] { "codes": [ { "code": "import requests\n\nr = requests.get(\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR KEY]&_limit=[NUMBER OF ROWS]\")", "language": "python" }, { "code": "<?php\n\tch = curl_init();\n\tcurl_setopt($ch, CURLOPT_HEADER, 0);\n\tcurl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);\n\tcurl_setopt($ch, CURLOPT_CONNECTTIMEOUT,20);\n\tcurl_setopt($ch, CURLOPT_URL, \"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR KEY]&_limit=[NUMBER OF ROWS]\");\n\t$result = json_decode(curl_exec($ch));\n\tcurl_close($ch);\n?>", "language": "php" }, { "code": "require 'unirest'\n\nresponse = Unirest.get(\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR KEY]&_limit=[NUMBER OF ROWS]\")", "language": "ruby" } ] } [/block] Example Response: [block:code] { "codes": [ { "code": "{\"status\":200,\n \"message\":\"Success\",\n \"body\":[\n \t{\n \t\t\"_id\":\"FSBEQAKJQJH059881.299319683364711375720224963\",\n \t\t\"lobbyist_first_name\":\"James\",\n \t\t\"lobbyist_last_name\":\"Connolly\",\n \t\t\"filing_year\":\"2012\"\n\t\t},\n\t\t{\n \t\"_id\":\"FSBEQAKJQJH059857.653845592045361375720225585\",\n \t\"lobbyist_first_name\":\"James\",\n \t\"lobbyist_last_name\":\"Gilliam\",\n \t\"filing_year\":\"2012\"\n \t},\n\t\t{\n \t\t\"_id\":\"FSBEQAKJQJH05984.6746827350097781375720228202\",\n \t\t\"lobbyist_first_name\":\"James\",\n \t\t\"lobbyist_last_name\":\"Alexander\",\n \t\t\"filing_year\":\"2012\"\n\t\t},\n\t\t{\n \t\t\t\"_id\":\"FSBEQAKJQJH059878.41251410109141375720234876\",\n \t\t\"lobbyist_first_name\":\"James\",\n \t\t\"lobbyist_last_name\":\"Banks\",\n \t\t\"filing_year\":\"2012\"\n\t\t},\n\t\t{\n \t\t\"_id\":\"FSBEQAKJQJH059890.543216294539121375720235255\",\n \t\t\"lobbyist_first_name\":\"James\",\n \t\t\"lobbyist_last_name\":\"Darnell\",\n \t\t\"filing_year\":\"2012\"\n\t\t},\n\t\t{\n \t\"_id\":\"FSBEQAKJQJH059884.74339911080541375720244224\",\n \t\"lobbyist_first_name\":\"James\",\n \t\"lobbyist_last_name\":\"Henn\",\n \t\"filing_year\":\"2012\"\n \t},\n\t]\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "OAuth Access Token: Creating, Deleting and Editing Datasets" } [/block] Gaining write access to data hosted on Exversion requires a more secure from of authentication. Exversion supports OAuth, issuing access tokens that do not expire but can be revoked. [block:callout] { "type": "info", "title": "But I Just Want Access to My Own Account!", "body": "It's annoying when you want to write scripts that will only ever try to access your account and you have to waste time and energy building a completely unnecessary OAuth client just to generate and fetch the access token. We hate that, so we built in an [OAuth client into Exversion's web interface](https://exversion.com/oauth/remote/) that will generate the token for you.\n\nThis token is just for personal use. If you plan on building an application that other people will use to manipulate their accounts, you will have to support OAuth." } [/block] The first step in generating an access token is [registering your application with Exversion](https://exversion.com/oauth/create/). This will generate a Client ID and Secret for your application to use. To start the authorization process is to send a request to the following URL: [block:code] { "codes": [ { "code": "http://www.exversion.com/oauth/v2/auth?client_id=[CLIENT ID]&response_type=code&redirect_uri=[REDIRECT URL]", "language": "text" } ] } [/block] If the client id matches a valid Exversion App the user will be redirected to a page asking them to allow or deny your app. Once they click ALLOW they are redirected back to your app via the redirect url specified when you registered your app. A code will be appended to the redirect url like so: [block:code] { "codes": [ { "code": "http://www.example.com/?code=[CODE HERE]", "language": "text" } ] } [/block] Once you have the code, you can generate the access_token by sending the following request back to Exversion [block:code] { "codes": [ { "code": "http://www.exversion.com/oauth/v2/token?client_id=[CLIENT ID]&client_secret=[CLIENT SECRET]&grant_type=authorization_code&redirect_uri=[REDIRECT URL]&code=[CODE HERE]", "language": "text" } ] } [/block] The response from Exversion will look like this: [block:code] { "codes": [ { "code": "{\n \"access_token\": \"8315796acc79f6a1bfb4e4935aea01362d59ecce\",\n \"token_type\": \"bearer\",\n \"scope\": null,\n}", "language": "json" } ] } [/block] Include the access token as part of any requests that create, edit or delete information from Exversion.