Authentication¶

Users authenticate via OAuth2 Authorization Code flow with PKCE. When a user needs to access Unomed, they log in through the Unomed login page and are redirected back to your system.

OAuth2 Flow Overview¶

Unomed iframe redirects to /o/authorize/ when user is not authenticated or API returns HTTP 401
User logs in with their Unomed credentials
Unomed redirects to your redirect_uri with query parameter ?code={authorization_code}
Your backend calls POST /o/token/ with grant_type=authorization_code to exchange for access_token and refresh_token
Store the refresh_token securely per user. The refresh token is valid for 30 days. Each time you call /o/token/ with grant_type=refresh_token, you receive a new refresh_token with a fresh 30-day validity. Your backend should refresh tokens automatically to keep users logged in.

Generate a PKCE code_verifier (random string) and code_challenge (SHA256 hash of verifier, base64url encoded).

Redirect the user to the authorization endpoint:

https://api.dev.unomed.ch/o/authorize/?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=openid&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256&
  response_mode=query

PKCE Example (Python)¶

import base64
import hashlib
import os

# Generate code_verifier (store this for step 3)
code_verifier = base64.urlsafe_b64encode(os.urandom(32)).rstrip(b"=").decode("ascii")

# Generate code_challenge
code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode("ascii")).digest()
).rstrip(b"=").decode("ascii")

Step 2: Handle the Redirect¶

After login, Unomed redirects to your redirect_uri with the authorization code:

https://your-app.com/callback?code=AUTHORIZATION_CODE

Step 3: Exchange Code for Tokens¶

curl -X POST https://api.dev.unomed.ch/o/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "code_verifier=CODE_VERIFIER"

Response¶

{
  "access_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 43200,
  "refresh_token": "xyz789...",
  "scope": "openid",
  "id_token": "eyJ..."
}

Token Expiry¶

Token	Validity
Access Token	12 hours
Refresh Token	30 days (extended on each refresh)

Step 4: Refresh the Token¶

Before the access token expires, use the refresh token to get a new one:

curl -X POST https://api.dev.unomed.ch/o/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID"

The response includes a new access_token and a new refresh_token. Store the new refresh token - it extends the 30-day validity.

Using the Token¶

Include the access token in all API requests:

curl https://api.dev.unomed.ch/fhir/r4/Patient \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Automatic Token Refresh¶

Your backend should automatically refresh tokens before they expire to keep users logged in without requiring re-authentication.

Recommended approach:

Store the refresh_token and expires_in timestamp when you receive tokens
Before making API calls, check if the access token is expired or about to expire
If expired, call /o/token/ with grant_type=refresh_token to get new tokens
Store the new refresh_token - it extends the 30-day validity