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.


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)
# ๐Ÿ‡จ๐Ÿ‡ฆ Canada Sandbox (testing)

Production applications

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

# ๐Ÿ‡บ๐Ÿ‡ธ US Production
# ๐Ÿ‡จ๐Ÿ‡ฆ Canada Production

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:


Thereโ€™s no need to add scopes to the request; any scopes added this way are ignored. Scopes you configured via the Fullscript API Dashboard are automatically applied to your request.

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:


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

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.

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

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


The authorization code has a 10 minute lifetime. You must use it to request an OAuth access token within 10 minutes, or you'll need to re-request user authorization.