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 AidboxUserwhose 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-adminfor the administrator roleepcs-access-approverfor the approver roleepcs-prescribingfor 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
Userthat 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.fhirUserreferences aPractitionerwhoseactiveis notfalse.- That
Practitionerhas at least onePractitionerRolewith all of these:- A reference to the location.
activeset totrue.period.startin the past andperiod.endin the future. Both dates are required.- An
identifierwith the type codeDEAfromhttp://terminology.hl7.org/CodeSystem/v2-0203and a DEA number invalue, such asAB1234563.
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:twoFactorCodeis 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: aLocationid.status:pending,approved,cancelled, orexpired.
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.