Authentication

Get account information

  • Sandbox: available
  • Staging: available
  • Production: unknown
GET
/auth/me

Returns the signed-in user's context: project, membership, profile, user configuration, access policy and security details such as MFA status and sessions. Call it after sign-in to learn who the token belongs to.

Auth: bearer token. A missing, non-bearer or invalid token gives 401. Scope: the project of the token.

Behaviour

  • The answer is Medplum's auth/me for the token's session.
  • The call always discards Ovok's cached copy of this session's profile and reads a fresh one, so changes to the profile or access policy show up in the response and in later requests with the same token.
  • Use the returned profile.resourceType to tell Patients from Practitioners.

Example

curl -X GET 'https://api.sandbox.ovok.com/auth/me' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Response Body

User profile returned.

application/json
  1. response
project*
membership*
profile*
config*
accessPolicy*
security*
Example Request
curl -X GET 'https://api.sandbox.ovok.com/auth/me'
Example Response
{  "project": {    "resourceType": "Project",    "id": "string",    "name": "string",    "strictMode": true  },  "membership": {    "resourceType": "ProjectMembership",    "id": "string",    "user": {      "reference": "string",      "display": "string"    }  },  "profile": {    "resourceType": "Patient",    "id": "string",    "name": [      {        "given": [          "string"        ],        "family": "string"      }    ],    "telecom": [      {        "system": "string",        "use": "string",        "value": "string"      }    ]  },  "config": {    "resourceType": "UserConfiguration",    "menu": [      {        "title": "string",        "link": [          {            "name": "string",            "target": "string"          }        ]      }    ]  },  "accessPolicy": {    "resourceType": "AccessPolicy",    "resource": [      {        "resourceType": "string"      }    ],    "ipAccessRule": [      {        "ip": "string"      }    ]  },  "security": {    "mfaEnrolled": true,    "sessions": [      {        "id": "string",        "lastUpdated": "string",        "authMethod": "string",        "remoteAddress": "string"      }    ]  }}

Login POST

Signs a user in with email and password for the project that owns a client application, and returns an access token and a refresh token. New integrations should use the tenant login routes (`/auth/tenant/Patient/login/start` and `/auth/tenant/Practitioner/login/start`) instead. **Auth:** none. The email and password are the credential, and `clientId` names the project. **Scope:** the project that owns the `ClientApplication` with the given `clientId`. ## Behaviour - Ovok looks up the account by email in the client application's project. If a Patient and a Practitioner share the email in that project, one of them is picked and which one is not defined. - The account type's login switch must be on: the project setting `PATIENT_LOGIN_ENABLED` or `PRACTITIONER_LOGIN_ENABLED`. Both default to on. It is checked once the password is right, so its 403 never tells which emails have an account. - A wrong password and an unknown email give the same 401 `Invalid email or password.`, so the response does not tell you which one was wrong. An unknown `clientId` gives a 400. - After 5 failed sign-ins for one email within 15 minutes, that email's sign-ins answer 429 with `Retry-After` for 15 minutes, the right password included, whether or not the email has an account. A successful sign-in resets the count. - If Medplum's own login rate limit is hit, you get a 429 instead of a 401. Wait and retry. - Callers without a token may send at most 10 requests per minute from one IP address. - A successful login cancels a pending account deletion (`DELETE /auth/delete`). - This route has no MFA step. Use the tenant login routes for users with MFA enrolled. - The access token lasts one hour (`expiresIn` is in seconds). Use `POST /auth/refresh-token` to renew it. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v2/auth/login' \ -H 'Content-Type: application/json' \ -d '{ "email": "max.mustermann@example.com", "password": "Ex4mple-Passw0rd", "clientId": "c3499c27-2973-0a7f-807e-fb8676a92dcb" }' ```

Get all sessions GET

Lists the caller's live sessions (one per sign-in). Use it to build a "where you are signed in" screen. **Auth:** bearer token. **Scope:** the signed-in user's own sessions. ## Behaviour - A session is listed when its Login belongs to the user, has a project membership and is not revoked. Sessions that have been idle for a long time are listed as long as they are not revoked. - The list is ordered newest first. - `browser` and `os` are `null` for sessions that Medplum does not report them for. - The call only reads. It does not change any session. ## Example ```bash curl -X GET 'https://api.sandbox.ovok.com/auth/session' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```