drchrono.com

This document is intended as a detailed reference for the precise behavior of the drchrono API. If this is your first time using the API, start with our tutorial . If you are upgrading from a previous version, take a look at the changelog section. Authorization Initial authorization There are three main steps in the OAuth 2.0 authentication workflow: 1. Redirect the provider to the authorization page. 2. The provider authorizes your application and is redirected back to your web application. 3. Your application exchanges the authorization code that came with the redirect for an access token and refresh token . Step 1: Redirect to drchrono The first step is redirecting your user to drchrono, typically with a button labeled "Connect to drchrono" or "Login with drchrono". This is just a link that takes your user to the following URL: https://drchrono.com/o/authorize/?redirect uri=REDIRECT URI ENCODED&response type=code&client id=CLIENT ID ENCODED&scope=SCOPES ENCODED - REDIRECT URI ENCODED is the URL-encoded version of the redirect URI (as registered for your application and used in later steps). - CLIENT ID ENCODED is the URL-encoded version of your application's client ID. - SCOPES ENCODED is a URL-encoded version of a space-separated list of scopes, which can be found in each endpoint or omitted to default to all scopes. The scope parameter consists of an optional, space-separated list of scopes your application is requesting. If omitted, all scopes will be requested. Scopes are of the form BASE SCOPE:[read write] where BASE SCOPE is any of user , calendar , patients , patients:summary , billing , clinical and labs . You should request only the scopes you need. For instance, an application which sends "Happy Birthday!" emails to a doctor's patients on their birthdays would use the scope parameter "patients:summary:read" , while one that allows patients to schedule appointments online would need at least "patients:summary:read patients:summary:write calendar:read calendar:write clinical:read clinical:write" . Step 2: Provider authorization After logging in (if necessary), the provider will be presented with a screen with your application's name and the list of permissions you requested (via the scope parameter). When they click the "Authorize" button, they will be redirected to your redirect URI with a code query parameter appended, which contains an authorization code to be used in step 3. If they click the "Cancel" button, they will be redirected to your redirect URI with error=access denied instead. Note: This authorization code expires extremely quickly, so you must perform step 3 immediately, ideally before rendering the resulting page for the end user. Step 3: Token exchange The code obtained from step 2 is usable exactly once to obtain an access token and refresh token. Here is an example token exchange in Python: import datetime, pytz, requests if 'error' in get params: raise ValueError('Error authorizing application: %s' % get params[error]) response = requests.post('https://drchrono.com/o/token/', data={ 'code': get params['code'], 'grant type': 'authorization code', 'redirect uri': 'http://mytestapp.com/redirect uri', 'client id': 'abcdefg12345', 'client secret': 'abcdefg12345', }) response.raise for status() data = response.json() Save these in your database associated with the user access token = data['access token'] refresh token = data['refresh token'] expires timestamp = datetime.datetime.now(pytz.utc) + datetime.timedelta(seconds=data['expires in']) You now have all you need to make API requests authenticated as that provider. When using this access token, you'll only be able to access the data that the user has access to and that you have been granted permissions for. Refreshing an access token Access tokens only last 48 hours (given in seconds in the 'expires in' key in the token exchange step above), so they occasionally need to be refreshed. It would be inconvenient to ask the user to re-authorize every ti…