Authentication

How it works

1. Create an API key in the Developer Portal. Sandbox keys start with sk_test_, production keys with sk_live_.
2. Exchange the key for an access token at the token endpoint.
3. Send the token as Authorization: Bearer <access_token> on API calls.
4. When the token expires, exchange your key again for a fresh one.

Token endpoint: https://api.mediloop.co/api/v1/auth/token (production) or https://sandbox.api.mediloop.co/api/v1/auth/token (sandbox). Use the host that matches your key.

1. Get your API key

Create an application in the Developer Portal and generate an API key. The key is shown only once — store it securely. Sandbox and production keys are separate; treat the key like a password and keep it server-side only.

2. Get an access token

POST your API key to the token endpoint. You can send it in the JSON body as api_key, or as an Authorization: Bearer <api_key> header.

curl -X POST https://api.mediloop.co/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_live_YOUR_API_KEY"
  }'

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "environment": "production"
}

The environment field reflects the key you used (sandbox or production).

3. Make authenticated requests

Send the access token in the Authorization header:

curl https://api.mediloop.co/api/v1/uhid/UG123456789A/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"

{
  "uhid": "UG123456789A",
  "first_name": "John",
  "last_name": "Doe",
  "gender": "M",
  "fhir_patient_id": "Patient/fhir-123"
}

Request headers

Access to patient data is consent-gated

A valid token authenticates you; it does not by itself grant access to a specific patient's records. Reading or writing a patient's clinical data additionally requires an active, minimum-necessary consent for that patient (and, for providers, a treating relationship). Every access is audited and visible to the patient, and consent can be revoked at any time. See Errors for the responses you get when consent is missing (403).

Token lifetime & security

• Access tokens are short-lived (see expires_in). Exchange your key for a new token when the current one expires; cache it until then rather than fetching one per request.
• Never expose your API key in client-side code. Exchange for tokens server-side only.
• Do not commit your API key to version control. Use environment variables or a secret manager.
• Use separate keys for sandbox and production; roll (regenerate) them from the Developer Portal if a key is ever exposed.

Environments

Sandbox and production have the same paths — you swap the base URL and use the matching key. Sandbox operates on isolated test data (and supports payment test numbers), so build and test against it freely before going live. Get your token from the token endpoint on the same host you're calling.

Error responses

An invalid or revoked API key returns 401 Unauthorized from the token endpoint; a valid token without the required consent/permission returns 403 Forbidden from the API.

{
  "error": "invalid_client",
  "error_description": "Invalid API credentials."
}

Related