Skip to main content
Before you can use the Squire SDK or Widget, each user session needs a valid access token. You request this token from your backend using your Squire API key, then pass it to the frontend to initialize the SDK. If you don’t have an API key yet, create one in the Portal.
Never make token requests from the client side. Your API key must remain secret and must only be used in your backend server environment.

​
Authentication flow

The token-based flow keeps your API key secure on the server while giving the frontend the short-lived credential it needs.
1

Frontend requests a token

Your EHR frontend calls an endpoint on your own backend to request an access token for the current user.
2

Backend calls the Squire API

Your backend sends a POST request to https://api.squire.eu/api/v1/token/ with your API key and the user’s details.
3

Squire validates and responds

The Squire API validates your API key and the user data, then returns a signed access token and its expiration timestamp.
4

Backend returns the token

Your backend passes the token back to the frontend — never the API key.
5

Frontend initializes the SDK

Your EHR frontend uses the access token to initialize the Squire SDK for that user’s session.

​
Request an access token

Send a POST request to the token endpoint from your server. All requests must include your API key in the X-Api-Key header.
Token requests must be made server-side only. The API key used to authenticate this request is a private secret and must never appear in client-side code.
Endpoint: POST https://api.squire.eu/api/v1/token/

​
Request headers

​
X-Api-Key
string
required
Your Squire API key for authentication. Generate this from the Squire Portal.
​
Content-Type
string
required
Must be set to application/json.

​
Request body parameters

​
user_id
string
required
The unique identifier for this user in your system. This ties the Squire session to a specific user in your EHR.
​
first_name
string
required
First name of the user.
​
last_name
string
required
Last name of the user.
​
organisation
string
required
The name of the organisation where the user works — for example, the practice, clinic, or hospital name.
​
healthcare_provider_identification_number
string
The official identification number for this healthcare provider — for example, a RIZIV number in Belgium. Separators between characters are allowed.
​
email
string
Email address of the user in your system.
​
healthcare_provider_type
string
The type of healthcare provider. Use the ID values from the table below. Providing this value improves the accuracy of generated consultation reports.

​
Healthcare provider type IDs

Use one of the following id values for the healthcare_provider_type parameter:
NameID
Anesthesiologistanesthesiologist
Cardiologistcardiologist
Dermatologistdermatologist
Dietitiandietitian
Emergency Doctoremergency_doctor
Endocrinologistendocrinologist
Gastroenterologistgastroenterologist
General Practitionergeneral_practitioner
Geriatriciangeriatrician
Gynecologistgynecologist
Hematologisthematologist
Home Nursehome_nurse
Hospital Nursehospital_nurse
Infectiologistinfectiologist
Nephrologistnephrologist
Neurologistneurologist
Nursing Home Nursenursing_home_nurse
Oncologistoncologist
Ophthalmologistophthalmologist
Orthopedicorthopedic
Otorhinolaryngologistotorhinolaryngologist
Pediatricianpediatrician
Physiotherapistphysiotherapist
Practice Nursepractice_nurse
Psychiatristpsychiatrist
Psychologistpsychologist
Pulmonologistpulmonologist
Radiologistradiologist
Rheumatologistrheumatologist
Surgeonsurgeon
Speech-Language Pathologistspeech_language_pathologist
Stomatologiststomatologist
Urologisturologist

​
Code examples

The following examples show how to request a token from your backend server. Replace YOUR_API_KEY with the key from your Portal. 
curl -X POST "https://api.squire.eu/api/v1/token/" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "doctor123",
    "first_name": "doctor",
    "last_name": "123",
    "organisation": "practice_name",
    "healthcare_provider_identification_number": "12345678901",
    "email": "doctor@123.com",
    "healthcare_provider_type": "general_practitioner"
  }'

​
Response

​
200 Successful response

A successful request returns an access token and its expiration timestamp. Pass the token value to the Squire SDK on your frontend. 
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2025-01-01T14:30:00Z"
}
​
token
string
required
A signed JWT access token. Pass this to the Squire SDK to initialize a user session.
​
expires_at
string
required
The token’s expiration time in ISO 8601 format. Request a new token before this time to keep sessions active.

​
Error responses

​
400 Bad request

Returned when the request is missing required parameters or contains invalid values. The response body is a list of validation errors. 
[
  {
    "loc": ["organisation"],
    "msg": "Field required",
    "type": "missing"
  }
]
Check the loc field in each error object to identify which parameter needs to be corrected.

​
401 Unauthorized

Returned when the API key is invalid or missing from the request headers. 
{
  "error": "Invalid API key provided"
}
​
error
string
A human-readable description of what went wrong.
Verify that your X-Api-Key header is present and matches a valid key from your Portal.

​
403 Forbidden

Returned when the user context in the request body is invalid or unauthorized. 
{
  "error": "Invalid user_id provided"
}
​
error
string
A human-readable description of what went wrong.

​
429 Too many requests

Returned when your backend exceeds the API rate limit. Wait for the number of seconds specified in retry_after before sending another request. 
{
  "error": "Rate limit exceeded",
  "retry_after": 60
}
​
error
string
A human-readable description of what went wrong.
​
retry_after
number
The number of seconds to wait before retrying the request.

​
Next steps

Now that you have a valid access token, continue with your chosen integration path:

SDK installation

Install the Squire JavaScript SDK and initialize it with your access token.

Widget installation

Embed the pre-built Squire Widget using your access token.