> ## Documentation Index > Fetch the complete documentation index at: https://developer.vetcove.com/llms.txt > Use this file to discover all available pages before exploring further. # Getting started with OAuth > Some tips to get you making your first requests ### Accessing the API This guide is for external integrations that need to work on behalf of users. The API is available through the `connect.vetcove.com` domain. You will need a Vetcove provision OAuth Application in our system to begin connecting Clinics and making requests. Please reach out to your support contact for help getting started. # Authentication Authentication to the Vetcove service is done via [OAuth 2.0](https://tools.ietf.org/html/rfc6749) to grant access to resources on behalf of our users. ## Important Values Once an account has been provisioned, head to your [Integrator Portal](https://pims.vetcove.com/integrator/) page to view your `Client Id` and list of connected clinics. These are going to be the gateway to interacting with Vetcove. ### Available OAuth 2.0 scopes You will need to specify what type of access the user is granting to your application when going through the OAuth 2.0 consent flow. The available scopes are: | Scope name | Description | | - | - | | all | Grants a token access to all scopes | | auto\_auth | Allows creation of links which will automatically login a client | | addresses:read | Read address records | | addresses:write | Modify address records | | clinics:read | Read clinic records | | clinic\_clients:read | Read clinic client records | | clinic\_clients:write | Modify clinic client records | | clinic\_patients:read | Read clinic patient records | | clinic\_patients:write | Modify clinic patient records | | appointments:read | Read appointment records | | appointments:write | Modify appointment records | | calendars:read | Read calendar records | | client\_onboardings:read | Read client onboarding records | | care\_plans:read | Read care plan records | | care\_plans:write | Modify care plan records | | patient\_standard\_care\_reminders:read | Read patient standard care reminder records | | invoices:read | Read invoice records | | labs:read | Read lab records | | prescriptions:read | Read prescription records | | external\_rx:read | Read external prescription records | | payment\_methods:read | Read payment method records | | payment\_methods:write | Modify payment method records | | payment\_transactions:read | Read payment transaction records | | payment\_links:read | Read payment link records | | payment\_links:write | Modify payment link records | | service\_pricing:read | Read service pricing configurations | | service\_pricing:write | Modify service pricing configurations | | catalog:read | Read catalog records | | subscriptions:read | Read subscription records | | orders:read | Read order records | | checkout\_links:read | Read checkout link records | | pdfs:read | Read PDF records | | pdfs:write | Modify PDF records | | uploaded\_files:read | Read which files have been previously uploaded | | uploaded\_files:write | Upload new files into the system | | inventory:read | Read which inventory codes exist and their associated settings | | inventory:write | Modify settings for inventory codes | | medical\_records:read | Read medical record, vital, and assessment records | | patient\_client\_relationships:read | Read patient client relationship records | | patient\_client\_relationships:write | Modify patient client relationship records | Note that while you may request any of the above scopes, not all features will be accessible to all users through the API. ## Clinic Authorization From your software, add in a "Connect with Vetcove" button that when clicked, will redirect the user (with a GET request) to the following url: `connect.vetcove.com/api/clinic/v1/app_store/oauth/authorize/?response_type=code&client_id=&scope=&state=&redirect_uri=&code_challenge=&code_challenge_method=S256` **Notes**: * The `client_id` in the URL is taken from the tokens page * The `scope` is a whitespace-delimited sequence of scopes you are requesting access to * The `state` value is a url encoded string that will be passed through to the redirect URI * The `redirect_uri` value is a fully-qualified url that has been whitelisted in the [Integrator Portal](https://pims.vetcove.com/integrator/) * The `code_challenge` is a [PKCE](https://tools.ietf.org/html/rfc7636) code challenge derived from a randomly generated `code_verifier`. Generate a random string (the `code_verifier`), then compute `BASE64URL(SHA256(code_verifier))` to produce the `code_challenge`. * The `code_challenge_method` must be `S256` **Clinic Account Specificiation**: Redirecting to `/api/clinic/v1/app_store/oauth/authorize/` will prompt the user to enter valid **Vetcove Clinic Credentials**. These are credentials that work on [https://pims.vetcove.com](https://pims.vetcove.com). ## Successful Authorization When a clinic successfully completes the Oauth grant, the redirect-uri specified will be called with the query parameters `?code=&state=` **Notes**: * The `code` will expire after 10 minutes and should be used immediately for requesting an `access_token` ## Requesting Access Tokens Once a `code` has been successfully delivered to your redirect uri, the `code`, `client_id`, and `client_secret` will be used for requesting `access_tokens` This is done with a `POST` request to `connect.vetcove.com/api/external/v1/app_store/oauth/token/` with the payload ```json theme={null} { 'code': , 'client_id': , 'client_secret': , 'grant_type': 'authorization_code', 'code_verifier': } ``` **Notes**: * The `code` is a one-time code * The `grant_type` of `authorization_code` is required * The `code_verifier` is the original random string used to generate the `code_challenge` in the authorization request If your application is configured with multiple `redirect_uris`, then `redirect_uri` is required as a part of the payload. This value needs to match what was in the `/api/clinic/v1/app_store/oauth/authorize/` call. Otherwise, a `400` response code and `Mismatching redirect URI.` error will be returned. ```json theme={null} { ... payload ..., 'redirect_uri': '' } ``` A response will be in the form: ```json theme={null} { 'access_token': , 'expires_in': 3600, 'token_type': 'Bearer', 'scope': 'clinic_clients:read clinic_patients:read', 'refresh_token': } ``` **Notes**: * The `access_token` has an expiry of 60 minutes * The `access_token` can be stored in temporary storage for subsequent requests * The `refresh_token` should be stored in long term storage for subsequent requests * Access Tokens must be submitted via `Authorization: Bearer ` header ## Requesting a Refresh Token We **strongly** recommend that you build your application to expect token expiry at any time. You can do this by adding an error handler for all requests in case they get an "expired token" error message. To request a new token, make another `POST` request to `connect.vetcove.com/api/external/v1/app_store/oauth/token/` with the payload ```json theme={null} { 'grant_type': 'refresh_token', 'refresh_token': , 'client_id': , 'client_secret': , } ``` **Notes**: * The `refresh_token` is the the token saved from the previous token grant * The `refresh_token` can be used only once, and subsequent requests require a new `refresh_token`. **Note:** There is a 5 minute grace period between when a `refresh_token` is used, and when it expires. This is useful when facing network issues during this API call. This means retries using the same `refresh_token` are allowed within this grace period. A response will be in the same form as above: ```json theme={null} { 'access_token': , 'expires_in': 3600, 'token_type': 'Bearer', 'refresh_token': } ```