Authentication

general the digitail api uses the oauth 2 0 https //www oauth com/ standard for authentication paired up with the authorization code grant https //www oauth com/oauth2 servers/access tokens/authorization code request/ with t https //www oauth com/oauth2 servers/pkce/ oauth 2 0 authorization code grant with pkce offers robust security features suitable for protecting sensitive clinic information enhanced security pkce mitigates code interception and replay attacks by adding a verification step during the authentication process user consent oauth 2 0 standards ensure that users explicitly grant permission for applications to access their data, maintaining privacy and compliance with regulations simplified integration oauth 2 0 is widely supported across programming languages and platforms, enabling developers to integrate with ease set up integrating with the digitail api involves the following steps register your application obtain api credentials by completing the https //digitail com/api access/ implement oauth 2 0 flow follow the oauth 2 0 authorization code grant with pkce flow to authenticate your application and obtain access tokens access data utilize the access token to make authorized requests to digitail api endpoints and retrieve clinic data you can add the retrieved access token directly in the documentation page to try out the endpoints easier implementing oauth 2 0 flow generate code verifier , code challenge and state variables these variables are used to ensure the integrity and security of generating & retrieving the access token that follows code verifier should be a cryptographically random generated string with lowercase & uppercase letters, digits and the punctuation characters between 43 and 128 characters long code challenge is the base64 url encoded version of the sha256 hashing of the code verifier state is a randomly generated uri encoded string used by your app to protect youself against csrf attacks that is used to verify the integrity of the response store the code verifier and state variables locally more information here https //www oauth com/oauth2 servers/pkce/authorization request/ from your software, add a button "connect with digitail" that will redirect the user to the following url curl curl l https //vet digitail io/oauth/authorize ?response type=code \&client id={client id} \&client secret={client secret} \&redirect uri=https //your redirect url com/callback \&state={state} \&code challenge={code challenge} \&code challenge method=s256 digitail will prompt the user for authentication the user authenticated and gives consent to give access to data specified digitail will redirect back to the callback url with the auth code & state params in the url the code is available for only 10 minutes and should be used immediately to request an access token request an access token by sending the following post request curl curl x post d grant type=authorization code d client id={client id} d client secret={client secret} d redirect uri=https //your redirect url com/callback d code verifier={code verifier} d code={code} https //vet digitail io/oauth/token digitail will respond with the payload json { "token type" "bearer", "expires in" 31536000, "access token" "eyj0exaioijkv1qilcjhbgcioijsuz ", "refresh token" "def50200a1b2c3 " } using the access token send the access token on every api request in the authorization header get https //vet digitail io/api/v1/appointments authorization bearer {access token} accept application/json requests run in the context of the clinic that belongs to the user who authorized your application if that user belongs to more than one clinic, select one by sending its id in the x clinicid header without the header, the user's default clinic is used token lifetimes token valid for notes authorization code 10 minutes exchange it for tokens immediately access token 1 year expires in in the token response, in seconds refresh token 1 year counted from the moment it is issued store both tokens securely and treat them like passwords only the access token is ever sent to the api the refresh token is only ever sent to the token endpoint refreshing the access token nothing refreshes automatically when the access token expires, or ahead of time if you prefer, request a new one from the token endpoint using the refresh token grant pkce parameters are not needed for this call curl x post https //vet digitail io/oauth/token \ d grant type=refresh token \ d refresh token={refresh token} \ d client id={client id} \ d client secret={client secret} { "token type" "bearer", "expires in" 31536000, "access token" "eyj0exaioijkv1qilcjhbgcioijsuz ", "refresh token" "def50200a1b2c3 " } every refresh returns a new access token and a new refresh token , and revokes both of the old ones in the same call refresh tokens are single use replace the stored refresh token with the new one as soon as the response arrives do not run two refreshes in parallel for the same user the second one fails because the first already revoked the token it is presenting refreshing at least once a year keeps the session alive indefinitely, because each refresh token is valid for one year from issuance the token endpoint is rate limited separately from the api, at 60 requests per minute per ip address handling expired or revoked tokens what you see cause what to do 401 unauthorized from an api endpoint access token expired or revoked refresh, then retry the request 401 from /oauth/token with "error" "invalid request" and a hint of token has expired or token has been revoked refresh token is dead send the user through the authorization flow again 401 from /oauth/token with "error" "invalid client" wrong client id or client secret check your credentials 400 from /oauth/token with "error" "invalid grant" authorization code expired, reused, or wrong code verifier / redirect uri restart the authorization flow oauth 2 0 flow diagram