For AI agents: the documentation index is at /docs/aidbox/llms.txt. A Markdown version of this page is available at /docs/aidbox/modules/eprescription/epcs/access-management/access-change-requests.md or by requesting it with the Accept: text/markdown header.
Aidbox Docs

Access-Change Requests

An access-change request grants or revokes one access manager role or the EPCS prescribing permission for one Aidbox User at one Location. An administrator at the location creates it, and the change takes effect when the request is approved.

Request a Change

The caller must be an administrator at the location.

POST /e-prescription/access/epcs/requests
Content-Type: application/json

{
  "action": "grant",
  "permissionCode": "epcs-access-approver",
  "userId": "<User id>",
  "locationId": "<Location id>"
}
  • userId: the Aidbox User whose role or permission the request changes, its access-change target.
  • action, one of:
    • grant: the request is a nomination, and its access-change target is the nominee.
    • revoke
  • permissionCode, one of:
    • epcs-access-admin for the administrator role
    • epcs-access-approver for the approver role
    • epcs-prescribing for the EPCS prescribing permission
Response

201 Created returns the access-change request with status: pending, or status: approved for an immediate revocation. Use the id of a pending request to approve or cancel it.

{
  "resourceType": "EPrescriptionAccessRequest",
  "id": "72bfe69d-0bf7-4691-8b0a-d40ad8624d51",
  "action": "grant",
  "permissionCode": "epcs-access-approver",
  "user": { "reference": "User/nominee" },
  "location": { "reference": "Location/clinic-1" },
  "status": "pending",
  "requestedBy": { "reference": "User/first-admin" },
  "requestedAt": "2026-09-29T10:00:00Z",
  "expiresAt": "2026-10-01T10:00:00Z"
}

An administrator may request changes to their own roles, including removing the last administrator at the location. To appoint a new administrator after that, use Bootstrap the First Administrator.

Error Responses
  • 400: a required field is missing or invalid.
  • 403: the request has no acting user, or the caller is not an administrator at the location.
  • 409, in either of these cases:
    • A pending, unexpired request already exists for the same user, permission, and location, whether it grants or revokes the permission.
    • During an immediate revocation, another call changed the location's roles or the revoked permission at the same time. Retry the call.
  • 422, in any of these cases:
    • A grant names a user who already holds the permission, or a revocation names a user who does not.
    • An administrator nomination names a User that does not exist.
    • An approver or prescribing nomination names a user who is not DEA-qualified.
    • The caller nominates themselves as approver while the location has no DEA-qualified approver. Otherwise they could accept the nomination themselves.

Prescribing Nomination

A request that grants epcs-prescribing is a prescribing nomination. Its nominee must be DEA-qualified at the location. An administrator may nominate themselves.

Any approver at the location other than the administrator who requested it can approve it through second-person approval, including the nominee.

Prescribing Revocation

A request that revokes epcs-prescribing is a prescribing revocation. The module revokes the permission even when its holder is no longer DEA-qualified.

When a practitioner must lose the permission, for example after a lost authentication factor or an expired DEA registration, an administrator requests the revocation. The module does not detect these events.

Any approver at the location other than the administrator who requested it can approve it through second-person approval, including the access-change target.

Immediate Revocation

An immediate revocation is a revocation that an administrator completes without a second person's approval or a two-factor code. A revocation is immediate in either of these cases:

  • It revokes the approver role while only one user holds that role at the location, DEA-qualified or not.
  • It revokes epcs-prescribing (the administrator's own included) while no user holds the approver role at the location.

If either case applies when an administrator creates the revocation, the module removes the role or permission right away and returns the request with status: approved.

DEA Qualification

A user is DEA-qualified at a location when:

  • User.fhirUser references a Practitioner whose active is not false.
  • That Practitioner has at least one PractitionerRole with all of these:
    • A reference to the location.
    • active set to true.
    • period.start in the past and period.end in the future. Both dates are required.
    • An identifier with the type code DEA from http://terminology.hl7.org/CodeSystem/v2-0203 and a DEA number in value, such as AB1234563.

Approve an Access-Change Request

POST /e-prescription/access/epcs/requests/<id>/approve
Content-Type: application/json

{
  "twoFactorCode": "<code>"
}

A pending, unexpired request can be approved in one of the three ways below.

First Approver

A location with no DEA-qualified approver cannot use second-person approval. There, the nominee of an approver nomination accepts it with their own two-factor code.

Second-Person Approval

A DEA-qualified approver at the location approves the request with their two-factor code. The approver cannot be the administrator who requested it. They cannot be its access-change target either, unless the request is a prescribing nomination or a prescribing revocation.

Administrator Approval

After the location's approvers change, a pending revocation can become an immediate revocation:

  • It revokes the approver role, and its access-change target is now the only user who holds that role at the location.
  • It revokes epcs-prescribing, and no user holds the approver role at the location.

Any administrator at the location can then approve it without twoFactorCode, including the administrator who requested it.

Result

200 OK returns the access-change request with status: approved, resolvedBy, and resolvedAt.

Errors:

  • 400: twoFactorCode is not a string.
  • 403: the request has no acting user, or the caller may not approve this request in any of the three ways.
  • 409: another call changed the request or the location's roles at the same time. Reload the request and retry.
  • 422: the request does not exist, is resolved or expired, the two-factor code is missing, the user already holds the granted permission or lacks the revoked one, or the nominee of an approver or prescribing nomination is not DEA-qualified.

Cancel an Access-Change Request

These users can cancel a pending, unexpired request:

  • Any access manager at the location.
  • The access-change target of a request that changes their access manager role, such as a nominee who declines an administrator or approver nomination.

The access-change target of a revocation that someone else requested cannot cancel it.

POST /e-prescription/access/epcs/requests/<id>/cancel

200 OK returns the access-change request with status: cancelled, resolvedBy, and resolvedAt.

Error Responses
  • 403, in any of these cases:
    • The request has no acting user.
    • The caller is neither an access manager at the location nor the access-change target of a request that changes their access manager role.
    • The caller is the access-change target of a revocation that someone else requested.
  • 409: another call changed the request or the caller's role at the location at the same time. Reload the request and retry.
  • 422: the request does not exist, or is resolved or expired.

List Access-Change Requests

GET /e-prescription/access/epcs/requests
GET /e-prescription/access/epcs/requests?location=<Location id>&status=pending

200 OK returns a searchset Bundle with:

  • Requests at locations where the acting user is an access manager.
  • Requests that name the acting user as the access-change target and change an access manager role.

Optional filters:

  • location: a Location id.
  • status: pending, approved, cancelled, or expired.

Without an acting user, the operation returns 403.

Expiration

A request expires 48 hours after requestedAt, at the time in expiresAt. After that:

  • Approval and cancellation return 422.
  • You can request the same change again.

The status of an expired request may still show pending, so check expiresAt instead.

Last updated: