Request an auth code

Once you've retrieved your app's client_id and client_secret, and set your app's OAuth scopes, the next thing to do is have a place in your app that triggers the user authorization process. See our OAuth overview for some helpful tips on creating this interface in your UI.

Query

A request to oauth/authorize is different from requests to other parts of our API. Instead of making a programmatic call to one of our endpoints, oauth/authorize is done via a browser redirect. The user clicks your app's Connect my Fullscript acccount or Add a Fullscript treatment plan button and you redirect the user's browser to the appropriate Fullscript authorize url.

Sandbox applications

Use the appropriate (US or Canada) OAuth authorization url below for apps under development.

# 🇺🇸 US Sandbox (testing)
https://us-snd.fullscript.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_APPLICATIONS_REDIRECT_URI&response_type=code
# 🇨🇦 Canada Sandbox (testing)
https://ca-snd.fullscript.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_APPLICATIONS_REDIRECT_URI&response_type=code

Production applications

When you make your application live, don't forget to update the authorization URLs to target our production auth servers.

# 🇺🇸 US Production
https://api-us.fullscript.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_APPLICATIONS_REDIRECT_URI&response_type=code
# 🇨🇦 Canada Production
https://api-ca.fullscript.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_APPLICATIONS_REDIRECT_URI&response_type=code

Example request

As shown in the query definition above, you need your App’s client_id, retreived from the Fullscript API Dashboard in our setup step. You must also provide the exact same redirect_uri you configured on the Dashboard. Your request will return 404 if there’s any mismatch.

For example:

https://api-us-snd.fullscript.io/api/oauth/authorize
  ?client_id=83x92x21xx29x643xx9954x8x2xx651xxx87x66521x08x9x2x408x26x801x394
  &redirect_uri=https://example.com/redirect
  &response_type=code

Optional state

You can optionally pass in a state parameter to the authorization code request. We don't process the state parameter, but instead, pass it back to you in the next step.

You can use the state paramater to do things like remember which page or part of a process your user was in before they were redirected to the Fullscript OAuth process.

If you want to keep track of more complex things, like the fact that the user was viewing a particular patient page, you can encode that data, then pass the encoded string in the state param:

state="some-encoded-state-data-that-my-app-needs"

To include the state option, just append it to your call:

https://api-us-snd.fullscript.io/api/oauth/authorize
  ?client_id=83x92x21xx29x643xx9954x8x2xx651xxx87x66521x08x9x2x408x26x801x394
  &redirect_uri=https://example.com/redirect
  &response_type=code
  &state=some-state-data-that-my-app-needs

User interaction

At this point, it's out of your hands for a few moments.

When redirected to our OAuth flow, users who aren’t already signed in to Fullscript are prompted to sign in or sign up for a Fullscript account. Once signed in, they are shown a detailed list of the access scopes your application is requesting, and they are asked to authorize your application.

The user can either cancel or authorize your application to access their Fullscript data.

Response (sort of)

Since this isn't your typical API call, it's not a typical response either.

Rather than having a response code returned to your application, users who authorize your app are redirected back to your redirect_uri. The query parameters returned include your new (temporary) authorization code for this user.

https://www.example.com/redirect
  ?code=476x028x13xxxx52xx4x2xx87x472x735xxx893570x89xx48x9496xxx2418052

If you passed in a state parameter, it's passed back to you:

https://www.example.com/redirect
  ?code=476x028x13xxxx52xx4x2xx87x472x735xxx893570x89xx48x9496xxx2418052
  &state=some-state-data-that-my-app-needs

Use the provided authorization code to call our OAuth token endpoint and request an access token to use on behalf of your user.