Authentication

4min
General
The Digitail API uses the OAuth 2.0 Standard for authentication paired up with the Authorization Code Grant with ﻿PKCE support.
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 ﻿access ﻿form﻿ 
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
1
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.
2
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
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
﻿
3
Digitail will prompt the user for authentication 
4
The user authenticated and gives consent to give access to data specified.
5
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
6
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
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
﻿
7
Digitail will respond with the payload:
JSON
{
  token_type: "Bearer",
  expires_in: "31536000", # time to expiration in seconds
  access_token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
  refresh_token: "def502001464837...",
  access_token_url: "https://vet.digitail.io/oauth/token",
  client_id: "9b8a5628-...",
  timestamp: "1712928761824" # when the request was made
}
{
  token_type: "Bearer",
  expires_in: "31536000", # time to expiration in seconds
  access_token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
  refresh_token: "def502001464837...",
  access_token_url: "https://vet.digitail.io/oauth/token",
  client_id: "9b8a5628-...",
  timestamp: "1712928761824" # when the request was made
}
﻿
OAuth 2.0 Flow Diagram
OAuth 2.0 Flow
﻿
﻿
Updated 03 Dec 2024
Did this page help you?
Introduction
Possible Errors