Access and Credentials

Aimedis has no partner program that issues API credentials. Access comes from whoever owns the data: the patient, the practice or the Wiki's administrators. This page explains each credential and walks through a patient's record share.

Each interface takes exactly one kind of credential, sent as a Bearer token. Keys and PINs are shown once and stored only as hashes.

• Wiki API key: awr_ followed by 43 characters, issued by a Wiki administrator for one application; expires after 1–365 days or never; can be rotated or revoked at any time; 120 requests per minute
• Practice-software credential: apx_ followed by 43 characters, created by a practice administrator in Aimedis Pro (Practice → Practice software) with the scopes appointments:read, appointments:write and results:write; no expiry, revoked in Pro; 600 requests per 10 minutes
• Aimedis Care record token: issued by POST /api/access/redeem for the patient's AIM-ID and PIN; valid for 15 minutes and limited to the categories the patient shared
• There is no self-service sign-up, sandbox or demo credential for any of these interfaces (Section 10)

Authorization: Bearer awr_…  # Wiki API key, from a Wiki administrator
Authorization: Bearer apx_…  # practice-software credential, from Aimedis Pro
Authorization: Bearer eyJ…   # Aimedis Care record token, from POST /api/access/redeem (15 minutes)

Send the credential in the Authorization header from your server only, never from a browser or mobile app: none of these interfaces sends CORS headers. Keep credentials out of URLs and logs.

Authentication Flow

1. 01The owner of the data issues the credential: the patient (a PIN share), the practice administrator (apx_) or a Wiki administrator (awr_)
2. 02Your server sends it as Authorization: Bearer on each request; an Aimedis Care PIN is first exchanged for a 15-minute token
3. 03Every request is checked again: a revoked key, a revoked share or a missing scope is refused at once
4. 04Each access is written to an audit log: Aimedis Care's hash-linked log for record reads and practice-software calls, the Wiki's audit for API keys

A patient's record share in four calls to https://care.aimedis.com. The patient creates the share in Aimedis Care and gives you the AIM-ID and PIN; nothing here can create, list or revoke a share, only the patient can, in the app. The examples use fictional values.

POST /api/access/redeem
Host: care.aimedis.com
Content-Type: application/json

{
  "patientId": "AIM-123456ABC",
  "pin": "<the PIN the patient gave you>"
}

→ 200 OK
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9…",
  "token_type": "Bearer",
  "scope": ["vitals", "diagnoses", "medications"],
  "expires_in": 900
}

→ 401
{ "error": "Invalid patient ID or PIN" }

GET /api/access/records
Host: care.aimedis.com
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…
Accept: application/fhir+json

→ 200 OK (application/fhir+json)
{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    { "resource": { "resourceType": "Observation", … } },
    { "resource": { "resourceType": "Condition", … } }
  ]
}

GET /api/fhir/Observation?_count=50
Host: care.aimedis.com
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…

→ 200 OK: a searchset Bundle with total and, while more remain, a next link (_count, _offset)
→ 403 OperationOutcome "forbidden": the patient did not share this category

GET /api/fhir/Patient/{id}/$summary
Host: care.aimedis.com
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…

→ 200 OK: a document Bundle; Composition LOINC 60591-5 with the sections
  medications, allergies, problems, results and vital signs

Aimedis Care's FHIR endpoint (FHIR 4.0.1) is read-only. The token's categories decide which resource types you can read. Search accepts only _id, _count and _offset; the diary summary appears only in GET /api/access/records.

profile

Patient

vitals

Observation (vital-signs)

laboratory

Observation (laboratory)

diagnoses

Condition, AllergyIntolerance

medications

MedicationStatement

documents

DocumentReference

diary

DocumentReference

Aimedis Pro, Aimedis Rehab and Aimedis Decision offer these interfaces. Only Pro's practice-software endpoints are for unattended server-to-server use; the Rehab and Decision endpoints serve signed-in patients and clinicians who download or upload a file. Aimedis Support offers no API for other systems.

Three hand-offs between Aimedis apps that matter for integrators. They run inside the family; outside systems take part only through the interfaces in Section 06.

1. 01

   Booking reaches the practice

   Bookings made in Aimedis Booking appear in Aimedis Pro's practice schedule. Practice software reads them through Pro's FHIR Appointment search or HL7 SIU feed and can block busy times there (Section 06).

2. 02

   Intake, with consent

   Aimedis Pro opens an intake with the patient's AIM-ID and intake PIN, or through a visit grant the patient gives for one appointment (at most 3 days). With an account, the answers are also sent to Aimedis Care, where the patient confirms them item by item.

3. 03

   Verification gates access

   Professional status comes from Aimedis Pro. Connect treats a clinician registered in Pro (not a Pro administrator account) as verified and lets that professional open a record a patient shares in a chat; Aimedis Care checks the professional status again before it issues a token.

What the platforms guarantee, and what remains your responsibility.

• Aimedis Care alerts the patient when a share is used (at most once per share in 6 hours) and shows every access in the patient's access history
• A revoked share or key is refused on the next request, and an Aimedis Care token never outlives its 15 minutes
• Aimedis Care writes record reads, PIN exchanges and Pro's practice-software calls to an append-only audit log whose entries are linked by SHA-256 hashes; an administrator can verify the chain
• Your own processing of the data needs its own legal basis and agreements; none of these interfaces carries a certification
• There is no break-glass access for professionals: in an emergency, only the patient's own emergency card shows information

Before you rely on an interface in production, check the following.

• You ask patients to share only the categories you need, and practices for only the scopes you need
• Credentials stay on your server: never in a browser, mobile app, URL or log
• Your error handling covers 400, 401, 403, 404, 413, 429 (with Retry-After) and 503, and never retries a refused PIN automatically
• Your integration treats a revoked share or key as an expected state, not a bug
• You have reviewed the data-protection rules of your target market (for example the GDPR in the EU)
• You have tested the whole flow with fictional data, including an expired or revoked credential

None of the following is available today. Only the last item is planned, and only for a concrete partner project; no date is set. Do not build against them.

• Webhooks

  Not offered. Aimedis apps notify each other only through signed server-to-server requests that outside systems cannot use.

• Self-service credentials

  Not offered. Credentials come from a Wiki administrator (awr_ keys), a practice administrator in Aimedis Pro (apx_ credentials) or the patient (a PIN share).

• Client libraries

  Not published. The Wiki team can provide TypeScript and Python sample clients for the Wiki API; there are none for the care platforms.

• Sandbox environment

  Not offered: there is no public test environment with synthetic data.

• Interface gateway

  Planned only for a concrete partner project, not built: a separate gateway, for example for HL7 v2 over MLLP and SMART Backend Services.