Once you've retrieved your app's
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.
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
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
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.
https://api-us-snd.fullscript.io/api/oauth/authorize ?client_id=83x92x21xx29x643xx9954x8x2xx651xxx87x66521x08x9x2x408x26x801x394 &redirect_uri=https://example.com/redirect &response_type=code
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
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
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.
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
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:
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.
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.