Authentication and Verification

The Doximity API allows partners to utilize Doximity’s clinician verification engine to verify the identity of a user and allow the user to authenticate using her Doximity credentials. That’s right, one less username and password for a doctor to remember, less friction during registration and confirmation that the user is a clinician.

OAuth Authorization

Doximity uses the server-side flow of the OAuth2.0 specification to authenticate a user and verify her identity against the Doximity national directory of healthcare providers.

Note: All requests must be sent over HTTPS.

Step 1 - Redirect the user to the Doximity OAuth Dialog

GET https://www.doximity.com/oauth/authorize?
    client_id=YOUR_APP_ID
    &response_type=code
    &redirect_uri=https://yourapp.com/callback
    &scope=basic%20colleagues
    &type=verify
    &state=SOME_ARBITRARY_BUT_UNIQUE_STRING

The “scope” parameter is optional and takes a space delimited list of available scopes. We recommend that you use the smallest possible scope to minimize the friction of registration for your site. The available scopes are currently: - Basic: Returns the user’s profile via the profile API. This is also the default scope if no other scopes are declared. - Colleages: Returns the colleagues list via the colleages API. - Email: Returns the user’s registered email address. The user must explicitly approve this access during OAuth confirmation.

The optional “type” parameter controls which of two landing pages is presented to the user. The value “verify” can be used in cases where emphasis is on using Doximity’s identity verification engine. We provide the following graphic for use with the verify landing page:

alt alt

The value “login” is the default for the “type” parameter and can be used in cases when a user is expected to login frequently. The OAuth flow remains the same in both cases, only the landing page changes. We provide the following graphic for use with the login landing page:

alt alt

Step 2 - The user is prompted to authorize your application

If the user does not yet have a Doximity account, they will be taken through Doximity’s verification process to create credentials and verify their identity as a clinician. If the user has a Doximity account but is not logged in, they will login using their existing credentials. If the user is already logged in to Doximity, they will be presented with the authorization screen. The user must approve your sites access to his or her Doximity account.

Step 3 - The user is redirected back to your site

If the user authorized your application, the user will be redirected to:

GET YOUR_REDIRECT_URI?
      state=YOUR_STATE_VALUE
    &code=DOXIMITY_GENERATED_CODE

If the user did NOT authorize your application, the user will be redirect to:

GET YOUR_REDIRECT_URI?
      error_reason=user_denied
      &error=access_denied
      &error_description=The+user+denied+your+request.

Step 4 - Exchange the code for a User Access Token

After the user has authorized your application, you can make a server-side request to exchange the code you received in step 3 for an user access token. You make this request through a post call including the following parameters: - grant_type: always “authorization_code” - code: the code you received in step 3 - redirect_uri: this must be the EXACT same value from step 1 - client_id: this is the client id issued by Doximity, same as step 1 - client_secret: this is the secret key issued by Doximity. You cannot share this key with anyone or make it available on an server that is accessible to unauthorized personnel.

Here is an example of a call:

POST /oauth/token HTTP/1.1
  Host: www.doximity.com
  Content-Type: application/x-www-form-urlencoded;charset=UTF-8

  grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
  &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
  &client_id=123455678&client_secret=KJHGAJ981JaslkjasdlkjLKJ230hsdkjljkl230a

The server will respond with the access token in the following format.

HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8
    Cache-Control: no-store
    Pragma: no-cache

    {
        "access_token":"2YotnFZFEjr1zCsicMWpAA",
        "token_type":"bearer",
        "expires_in":3600,
        "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    }

Step 5 - Make requests to the Doximity API

Once you have an access token for a specific user from step 4, you can query against the Doximity API. For example:

GET https://www.doximity.com/api/v1/users/current?access_token=YOUR_ACCESS_TOKEN