{"id":"c56ffe1fdae3e","branch_node_id":199137701,"type":"article","uri":"/docs/Getting-Started-with-the-Loopio-API.md","slug":"c56ffe1fdae3e-getting-started-with-the-loopio-api","title":"Getting Started with the Loopio API","summary":"Only Loopio Admins can create a Client, but anyone can use the Client (so be careful who you give it to!)","project_id":"cHJqOjIxMTk1MQ","branch_id":"YnI6NTI1MTE4NA","branch":"master","links":{},"outbound_edges":[{"id":"c56ffe1fdae3e","type":"article","slug":"c56ffe1fdae3e-getting-started-with-the-loopio-api","title":"Getting Started with the Loopio API","uri":"/docs/Getting-Started-with-the-Loopio-API.md"}],"inbound_edges":[],"data":"# Getting Started with the Loopio API\n\n## Creating a Loopio App Client\n\nOnly Loopio Admins can create a Client, but anyone can use the Client (so be careful who you give it to!)\n\n1. As an Admin, sign in to Loopio and access the Admin/Integrations page\n2. Scroll to the **For Developers** section and click Add an App\n3. Name your app and select the scopes you want it to have access to (see the API schema documentation to see which endpoints use which scopes)\n4. Once saved, you will see your Client’s ID and secret. These will be used to authenticate with Loopio. The secret will only be visible while you remain on this page. \n\n## Authenticate to use your Client\n\nLoopio follows the OAuth2 standard for authentication, and clients are authenticated using the client_credentials flow. \n\nBe aware that you need to choose the right host `api.loopio.com` or `api.eu.loopio.com` depending on what datacenter you are sending the request to. Loopio has datacenters in North America and in Europe, and the credentials generated for one of them will not work with another one. **Disclaimer**: the European API hasn't been made accessible yet. At this time please only use `api.loopio.com` host.\n\n1. To request an access token, send the following to https://api.loopio.com/oauth2/access_token\n\nDisclamer: If you’ve been given int01 testing instances, then a separate API key and credentials need to be created within those environments. Use api.int01.loopio.com as host.\n\n```\nPOST /oauth2/access_token \nHost: api.loopio.com\nContent-Type: application/x-www-form-urlencoded\n\ngrant_type=client_credentials\n&scope=library%3Aread+library%3Awrite\n&client_id=xxxxxxxxxxxx\n&client_secret=xxxxxxxxxx\n```\n\nResponse (status 200)\n```json\n{\n  \"token_type\":\"Bearer\",\n  \"expires_in\":3600,\n  \"access_token\":\"xxxxxxxxxxx\"\n}\n```\n\n2. You can now make requests to https://api.loopio.com/ by adding the Authorization header to your requests.\n\n```\nAuthorization: Bearer {your-token}\n```\n\n## Understanding Scopes\n\nScopes describe the permissions needed for API calls. An API client must be authorized with scopes matching the API endpoint it is calling. For example, an API client with only the `library:read` scope can call the [Get a Library Entry](https://developer.loopio.com/docs/loopio-api/0ce6a44706de7-get-a-library-entry) endpoint because that is the only scope required. It cannot call the [Create a Library Entry](https://developer.loopio.com/docs/loopio-api/bedaddd3877a9-create-a-library-entry) endpoint because it would require the `library:write` scope.\n\nTo make sure your API calls will be authorized properly, you need to:\n\n1. Select all required scopes when creating an API App in Loopio\n2. Request an authentication token specifying the correct scope(s)\n\n### Selecting Scopes when creating an API App in Loopio\n\n- Scopes are assigned when creating a new API App on the Admin/Integrations page in Loopio.\n- Follow the [Principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) and only select the scopes your client will require.\n- Scopes cannot be changed once the API App has been created in Loopio. You will need to delete your App in Loopio and create a new one if you need different scopes.\n\n### Requesting an authentication token\n\n- Associate scopes with an authentication token by specifying them in the `scope` parameter of the token request.\n- You can specify multiple scopes by separating them with a space in your request, e.g. `library:read library:write`\n- **Note: A space character will be URL encoded to a `+` sign**. The example provided in the [Authenticate to use your Client](#authenticate-to-use-your-client) section shows an encoded request. The delimiter between scopes is still a space character.\n- Any API request that uses the provided token will have the same scopes. You do not need to request a new token unless it expires or you need a different set of scopes."}