Authentication¶
Metricis separates researcher, participant/caregiver, assessment-session, and programmatic credentials. Use the flow designed for the actor; do not exchange one credential type for another in client code.
Researcher sessions¶
Interactive staff sign in through /api/auth/login. The response and subsequent flow depend on account policy: an MFA-enrolled user receives an MFA challenge, and roles that require enrollment are restricted until setup is complete. Access and refresh tokens are tied to server-side session records so sessions can be reviewed and revoked.
Send an access token only in the bearer header:
Use the refresh flow defined by the deployed OpenAPI contract. Never log tokens or place them in URLs.
Participant and caregiver sessions¶
The participant portal requests a magic link at /api/portal/auth/request-link and verifies it at /api/portal/auth/verify. Verification creates a portal session and returns the account's authorized study or registry context.
Web clients should use the supported cookie mode so refresh credentials are carried in an HttpOnly, Secure, SameSite=Strict cookie. Native clients can use the token response path appropriate to their secure storage. A magic-link request returns a non-enumerating response whether or not an address is registered.
Actor attribution (participant versus caregiver) is tracked in the server session. The API does not trust a caller-supplied actor label as authority.
Programmatic tokens¶
The gated /api/v1/tokens routes let an interactive user mint, list, rotate, and revoke expiring API tokens. Tokens have explicit scopes and may be bound to one study. Authoring scopes require stronger permissions and a study binding. The plaintext token is returned only when minted or rotated; only a hash and identifying prefix are retained server-side.
Programmatic callers use:
Store tokens in an approved secret manager, set the shortest practical lifetime, grant minimum scopes, and rotate/revoke through an interactive session.
Assessment and delivery credentials¶
Assessment sessions and participant work use credentials issued for that delivery workflow. They are narrower than a researcher session and must remain bound to the intended participant, version, and task/session. Follow the exact OpenAPI contract for the deployed release.
Authorization after authentication¶
Every protected operation can additionally evaluate:
- researcher role and permission;
- study, registry, site, and participant context;
- participant-account relationship and current actor;
- consent purpose and withdrawal state;
- workflow state, signature, verification, or lock constraints; and
- API-token scope, study binding, expiry, and revocation.
A valid token is therefore necessary but not sufficient for access.
Security rules¶
- Require HTTPS outside local development.
- Never store durable web refresh credentials in JavaScript-readable storage.
- Never place magic-link, OAuth, or bearer tokens in logs, analytics, or support screenshots.
- Keep provider and integration secrets on the server.
- Treat 401 as an authentication failure and 403/404 according to the route's anti-enumeration behavior.
- Use the server's development-only login helpers only when development mode is explicitly enabled; they are not production authentication paths.
The live OpenAPI schema is authoritative for request/response fields and enabled routes.