Skip to Content
Consent & Approval

Consent & Approval

No application reads a user’s health data without that user’s explicit, scoped consent. This page describes how approval, grants, and revocation work.

Roles and surfaces

  • /oauth/* — authenticated by clientId/clientSecret (the partner). Your app initiates authorization and exchanges codes for tokens here.
  • /partner/consent/* — authenticated by the end-user session (the DPerspective app the user is already logged into). The user reviews pending approvals and grants, and revokes access here.

Approval

When your app starts the authorization-code flow, the platform creates a pending approval listing your app identity and each requested scope.

GET    /partner/consent/pending              # list pending approvals
POST   /partner/consent/pending/:id/approve  # approve (with approvedScopes)
POST   /partner/consent/pending/:id/deny     # deny
  • A pending approval expires if not acted on within its window (1–60 minutes, default 15).
  • The user may approve a subset of the requested scopes.
  • Approving zero scopes is treated as a denial — no grant, no token.

When the user approves at least one scope, the platform creates an active consent grant binding userId + clientId + the approved scopes, with:

  • a creation timestamp,
  • an expiry between 1 and 365 days after creation (default 90 days),
  • a status of active, expired, or revoked.

A request returns data only when an active, unexpired grant covers the requesting client, the target user, and the endpoint’s scope. Otherwise it is rejected with CONSENT_REQUIRED (HTTP 403).

Reviewing grants

GET /partner/consent/grants

Returns all grants for the user (active and inactive), each with the clientId, granted scopes, creation timestamp, expiry, and status. No grants returns an empty list (not an error).

Revocation

DELETE /partner/consent/grants/:id

Revoking a grant:

  • marks it revoked (the record is retained for accountability — grant history is never deleted),
  • cascades to invalidate every access and refresh token derived from that grant within 60 seconds.

After revocation, any subsequent request relying on that grant is rejected with CONSENT_REQUIRED.

Audit trail

Every consent change, and every served or denied PHI access, appends one append-only audit entry recording the clientId, userId, affected scope(s)/endpoint, action/outcome, and a UTC timestamp.

⚠️

The audit log never contains plaintext secrets, tokens, or PHI values. If an audit append fails for a data access, that access is rejected with ACCESS_NOT_RECORDED and no data is returned.

AuthenticationScopes