Single Sign-On (SSO)

Single Sign-On (SSO) lets patients already signed in to your site access the DrCare247 patient portal without signing in again. You can also open booking with service, state, product, and payment options preselected.

Your application handles authentication and generates a one-time code. DrCare247 exchanges it with your token endpoint through a server-to-server request, so the patient's password is not sent to DrCare247.

Terms used on this page

• One-time code: a short-lived, single-use value your system creates for one sign-in.
• action: the portal page the patient lands on.
• refid: your order or appointment reference, sent on the SSO link. Use a new one for every booking.
• user_id: your stable patient id, returned by your token endpoint.
• refId: the field where you send that same patient id when you create the patient with the Create Member API.

1. 1How it worksThe sign-in flow
2. 2The SSO linkcode, action, refid
3. 3paramsBooking pre-selections
4. 4Your token endpointRequest and response
5. 5Session expiry and logoutWhen only your site signs patients in
6. 6ChecklistBefore you go live

How it works

The sign-in flow has six steps, from issuing the one-time code to opening the requested portal page.

SSO sign-in flow In the patient's browser Server to server

1. 1Patient → Your siteChooses to continue to DrCare247
2. 2Your site → DrCare247Redirect to /sso?code=…&action=…Browser redirect with a one-time code
3. 3DrCare247 → Your token endpointPOST the codeServer to server, form-encoded by default
4. 4Your token endpoint → DrCare247200 { email, user_id }The patient's identity
5. 5DrCare247Finds or creates the patient and signs them in
6. 6DrCare247 → PatientLands signed inOn the page set by action: booking, messages or dashboard

1. The patient, already signed in on your site, chooses to continue to DrCare247.
2. Your site creates a one-time code for that patient and redirects them to the DrCare247 /sso link.
3. DrCare247 POSTs that code to your token endpoint, server to server.
4. Your endpoint returns the patient's identity.
5. DrCare247 finds the patient and signs them in. It looks for the patient in this order:
   • by email;
   • by your patient id (user_id), if you created the patient earlier through the Create Member API with the same value as refId;
   • if neither matches, it creates a new patient.
6. The patient lands signed in, on the page the action asks for.

The SSO link

Redirect patients to the SSO link on your assigned portal host. The link includes a one-time code and an optional destination.

SSO link

https://<your DrCare247 portal host>/sso?code=<one-time code>&action=<action>&refid=<your order id>&params=<encoded JSON>

Parameter	Required	Meaning
code	Yes	The one-time code your system created for this sign-in. Make it short-lived and single-use.
action	Recommended	The page the patient lands on. See Actions. Case-sensitive.
refid	Recommended for bookings	Your order or appointment reference, up to 50 characters. Use a new value for every booking. DrCare247 stores it on the appointment and returns it to you as ExtRefId in webhooks.
params	Optional	Booking pre-selections, as Base64-encoded JSON. See params.

refid is an order id, not a patient id

If you send a refid that already belongs to an appointment, the patient sees a page linking to that existing visit, or their unfinished booking resumes, instead of a new booking starting. This includes completed, scheduled and cancelled visits. Only an abandoned or deleted booking frees its refid for reuse. Never use the patient's id as refid, and always send action=create_appt with a refid.

Actions

Use action to choose the portal page the patient lands on: booking, their secure messages or their dashboard.

action	The patient lands on
create_appt	Booking for params.serviceCode, with the other params already selected. Without params, or without serviceCode, the service list.
message	The patient's secure messages. If messaging is not enabled for your account, an access-denied page.
dashboard	The patient's dashboard.
session_expired	The page in params.returnUrl, after the patient signs in again. See Session expiry.

If you leave out action, the patient lands on the dashboard, or on the service list when the link has a refid.

params

Use params to preselect booking details. Serialize the JSON, Base64-encode it, and then URL-encode the result, in that order.

JavaScript

const params = encodeURIComponent(btoa(JSON.stringify({
  serviceCode: "S101",
  residingState: "TX",
  paymentTypeCode: "PRE"
})));

The same from a shell (needs jq), building the full link:

Shell

PARAMS=$(printf '%s' '{"serviceCode":"S101","residingState":"TX","paymentTypeCode":"PRE"}' | base64 | tr -d '\n' | jq -sRr @uri)
echo "https://<your DrCare247 portal host>/sso?code=<one-time code>&action=create_appt&refid=ORDER-1001&params=$PARAMS"

Always URL-encode the Base64 value

Base64 output can contain +. If it is not URL-encoded, the + becomes a space and the link fails with a generic error. Use standard Base64 (with +, / and =), not the URL-safe variant (- and _), and only ASCII characters in the values. Field names are case-sensitive: spell them exactly as shown below, for example parentappointmentId with a lower-case a.

All fields are optional and no action rejects them, but only create_appt uses the booking fields. paymentTypeCode is checked for every action, so an INS or MEM value that isn't enabled stops even a dashboard or message link.

Field	Type	Meaning
serviceCode	string	The service to book, e.g. S101. DrCare247 gives you the codes at onboarding.
residingState	string	The two-letter code of the state the patient is in for the visit, e.g. TX.
specialityCode	string	The speciality code. DrCare247 gives you the codes at onboarding.
methodId	number	How the visit is booked: 1 = later, with a chosen provider · 2 = later, any provider · 3 = now, next available provider · 4 = now, with a chosen provider. Same codes as the Create Appointment API.
durationId	number	Appointment length: 5 = 5 min · 6 = 10 min · 1 = 15 min · 2 = 30 min · 3 = 45 min · 4 = 60 min · 7 = 90 min · 8 = 120 min. Same codes as the Create Appointment API.
paymentTypeCode	string	How the visit is paid: PRE, INS or MEM. See Payment type.
products	array	Products or medications the patient requests. See Products.
pharmacyExtRefId	string	Your pharmacy reference, if pharmacies are mapped for your account. Applied only when serviceCode is also sent.
groupCode	string	Your group code, as set up for your account. An unknown or inactive group shows error 635.
appointmentId	UUID	An unfinished (pending) booking to resume. Its saved details replace the other fields. Any other appointment shows error 740, or 481 if it isn't found.
parentappointmentId	UUID	The earlier consultation this visit follows up. See Follow-up visits.
returnUrl	string	Only for session_expired: the portal path to return to, e.g. /dashboard.

Example: urgent care, Texas, prepaid (you collect the payment), one product.

params (before encoding)

{
  "serviceCode": "S101",
  "residingState": "TX",
  "paymentTypeCode": "PRE",
  "products": [{ "code": "62135070190", "codeType": "NDC", "quantity": 1, "days": 30 }]
}

Payment type

Set this when you already know how the visit is paid: prepaid by you, by insurance, or through a membership plan.

Send paymentTypeCode inside params, not as a separate URL parameter.

• PRE (prepaid): you collect the payment. DrCare247 takes no payment.
• INS (insurance): Insurance must be enabled for your account.
• MEM (membership plan): Membership and online payment must be enabled for your account, and the patient (or their primary member) must have an active membership. For a dependent, the plan must cover more than one member.

Products

When the patient has already chosen products or medications on your site, send them in products so they arrive as part of the patient's request. This needs the medication-request feature enabled for your account. An unknown product code shows error 650.

products is a list of items like this:

One product

{ "code": "62135070190", "codeType": "NDC", "quantity": 1, "days": 30 }

• code: the product code. Product codes are agreed at onboarding.
• codeType: NDC, CDC, DCC or WSC.
• quantity and days: optional.
• refillCount: optional. A whole number, 1 or more: how many refills the patient requests after the initial prescription. The provider approves or rejects the request during the consultation. It is not charged. An invalid value shows error 871.

Follow-up visits

To book a follow-up to an earlier consultation, send parentappointmentId in params with action=create_appt. Add serviceCode to open booking directly; without it, the patient picks the service from the list.

• Its value is the appointmentId of the completed initial consultation (the same value you would send as parentId to Create Appointment) or its consultationId. Both are accepted.
• DrCare247 checks it at SSO sign-in, with the same rules as Create Appointment. If a check fails, the sign-in stops and the patient sees the error:
  • 666: follow-up visits are not enabled for your account;
  • 668: the consultation does not belong to the signed-in patient;
  • 670: the consultation is not an initial consultation;
  • 669: the consultation is not completed (a no-show also counts as completed).
• A follow-up can include products with refillCount.

Your token endpoint

During SSO, DrCare247 sends the one-time code to your token endpoint. Provide the endpoint URL and any required app ID, app secret, grant type, and redirect URI during onboarding.

Request from DrCare247. A form-encoded POST by default; JSON can be configured during onboarding:

Request from DrCare247

POST https://id.yoursite.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Origin: <your DrCare247 portal host name>

AppId=<id>&AppSecret=<secret>&code=<the code from the link>&redirect_uri=<uri>&grant_type=<type>

• The default field names are AppId, AppSecret, code, redirect_uri and grant_type. A field with no configured value is not sent.
• The Origin header is your DrCare247 portal host name, without https://.
• At onboarding we can adapt the request to your existing endpoint. We can rename any field (for example, AppId to client_id and AppSecret to client_secret), send JSON instead of a form, add static headers, or read the identity from a nested object in your response.

Response you return. HTTP 200 with JSON:

Your response

{
  "access_token": "<your token for this user>",
  "email": "[email protected]",
  "first_name": "Pat",
  "last_name": "Lee",
  "user_id": "<your stable patient id>",
  "phone": "5551234567"
}

Field	Required	Used for
email	Yes	Finding or creating the patient.
user_id	Recommended	Your stable patient id. If you created the patient through the Create Member API, send the same value you sent there as refId, so SSO links to that patient. For patients created by SSO, webhooks return it as RefId (member events) and memberRefId (appointment events).
first_name, last_name	Recommended	Creating a new patient.
phone	Optional	Saved as the patient's primary phone on every successful sign-in, replacing a different stored number. Send a 10-digit number, or 11 digits starting with 1. Any other characters (spaces, dashes, brackets, +) are ignored, and any other length is not saved. DrCare247 stores it with your account country's dialling code.
access_token	Optional	Sent back to your session-check URL as a Bearer token. See Session check.

warning

The sign-in fails if your endpoint returns any status other than 200, an empty body, or JSON without email.

Test your endpoint. Send the same request DrCare247 makes, with the default field names:

Test your token endpoint

curl -X POST "https://id.yoursite.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "AppId=<id>" \
  --data-urlencode "AppSecret=<secret>" \
  --data-urlencode "code=<a fresh one-time code>" \
  --data-urlencode "redirect_uri=<uri>" \
  --data-urlencode "grant_type=<type>"

Your endpoint should return HTTP 200 with a JSON identity response for a valid code, and reject any attempt to reuse that code.

Session expiry and logout

This section covers where patients go when their portal session expires or they log out, if your site is the only place they sign in.

You can choose to have patients sign in only through your site. DrCare247 then turns off its own login, signup and password pages for your account. Give us your login and logout URLs at onboarding.

When the portal session expires:

1. DrCare247 sends the patient to <your login URL>?returnUrl=<full portal URL>&action=session_expired.
2. Your site reads the return URL. It is not URL-encoded, so if the portal page had its own query string, those parameters appear in your URL too. Take everything between returnUrl= and &action=session_expired.
3. After the patient signs in, your site sends them to /sso?code=…&action=session_expired&params=…, with { "returnUrl": "<that URL>" } inside params.

Return exactly the URL you received. It must start with your DrCare247 portal address, or be a portal path starting with /. Any other returnUrl is ignored: the patient stays on the DrCare247 loading screen and is not redirected. Without a returnUrl, the patient lands on the dashboard.

Register a login URL without a query string of its own: DrCare247 adds ?returnUrl= to it as is.

When the patient logs out of the portal, DrCare247 sends them to your logout URL.

Session check

DrCare247 can check with you that the patient's session is still active while they use the portal. This needs three things: you give us a logout URL and a session-check URL, and your token response includes an access_token. Each time the patient moves to another portal page, DrCare247 sends:

Session check from DrCare247

POST <your session-check URL>
Authorization: Bearer <access_token from your token response>

There is no request body. Return 401 to end the DrCare247 session; DrCare247 then sends the patient to your logout URL. Any other response keeps the session open.

What the patient sees when something is wrong

Use this table when a patient following your SSO link lands on an error page, or not where you expected, to find the likely cause.

Situation	The patient sees
The code can't be exchanged: your endpoint fails, returns no email, or the code was already used (for example, because the patient reloaded the /sso page)	A "We couldn't verify your request" page. A custom message can be set for your account.
The patient's DrCare247 account is locked or inactive	The same "We couldn't verify your request" page
refid is longer than 50 characters, or belongs to another patient's visit	An "order reference not found" page
refid belongs to one of this patient's visits that is not an unfinished or abandoned booking (including completed, scheduled and cancelled visits)	A page linking to that existing visit. Use a new refid to book again.
refid belongs to this patient's unfinished booking	That booking, resumed
paymentTypeCode is not PRE, INS or MEM	A "payment status is not valid" page
paymentTypeCode is INS or MEM, but that payment type is not enabled for your account	An explanatory page
paymentTypeCode is MEM and there is no active membership	An explanatory page
With create_appt, a code in params (service, speciality, state, product, pharmacy, group or appointment) is not recognised	An error page that shows the response code and its message, with a link back to the home page. Booking does not continue. Only the first problem is shown.
params can't be decoded	A generic error page. Check that params is Base64-encoded and then URL-encoded.

Checklist

Check the following before enabling SSO for patients:

• Your token endpoint returns 200 with email and, ideally, user_id, first_name, last_name and phone.
• Your one-time codes are single-use and short-lived.
• Every booking uses a new refid of at most 50 characters.
• params is standard Base64-encoded and then URL-encoded, with field names spelled exactly as on this page.
• Every link with a refid also has action=create_appt.
• Your service, speciality, product and group codes match the ones DrCare247 gave you.
• If you also use the Create Member API, the patient id you send there as refId is the same value your token endpoint returns as user_id.
• You subscribe to webhooks to follow the appointment. Its ExtRefId is your refid.

Getting StartedCredentials to first bookingWebhooksPayloads, signatures, retriesAPI referenceEvery endpoint, field and code