Provider Access Grants
Provision, list, inspect, and revoke provider Scribe access grants for a workspace.
Provider access grants control which clinicians can access Scribe in a workspace. A grant maps a workspace and email address to Scribe access and is the single authority that both human provider login and machine-to-machine act-as-by-email delegation resolve against. A provider must hold an active grant to be logged in as or acted on behalf of.
These endpoints let workspace administrators provision Scribe access by email, list and inspect a workspace's grants, and revoke access - replacing manual database operations and internal provisioning workflows.
Grant Lifecycle
A grant moves through the following states:
pending_entity
Email-only invite with no bound provider entity yet. Becomes active once the provider's entity is bound through the login or verification flow.
pending_verification
Provider entity is bound but email verification is not yet complete.
active
Fully provisioned. The provider can log in and be targeted by act-as-by-email delegation.
revoked
Soft-deleted. The provider can no longer log in or be targeted. Previously revoked emails can be re-invited, creating a fresh grant.
When an admin supplies a known provider entity ID at creation time, the grant is created as active (the admin vouches for the identity). Omitting the entity ID creates a pending_entity grant.
Roles and Scopes
Each grant carries a role that determines the scopes the provider receives:
provider
Standard Scribe clinician access (default).
scribe_admin
Workspace-level Scribe administration.
Authorization
All endpoints require identity:admin scope for the target workspace, or global platform:admin. Creating, listing, and revoking grants is an administrative act gated on admin authority, not on the Scribe capabilities the grant confers.
Endpoints
Create a Provider Access Grant
POST /admin/scribe/grant
Provision a provider for Scribe access in a workspace.
Request body:
workspace_id
string (UUID)
Yes
Target workspace.
email
string (email)
Yes
Provider's email address.
provider_entity_id
string (UUID)
No
Known provider entity ID. When supplied, the grant is created as active. When omitted, the grant is created as pending_entity.
requires_mfa
boolean
No
Whether the grant requires multi-factor authentication. Defaults to false.
role
string
No
provider (default) or scribe_admin.
Responses:
201
Grant created. Returns the grant object.
403
Missing admin scope for the target workspace.
409
An active grant already exists for this workspace and email combination.
Idempotency follows the workspace-plus-email uniqueness constraint for non-revoked grants. A second active grant for the same email returns 409. A previously revoked email can be re-invited, creating a fresh grant while the revoked row is retained for audit.
List Provider Access Grants
GET /admin/scribe/grant
List a workspace's provider access grants with pagination. Returns metadata only - no secrets.
Query parameters:
workspace_id
string (UUID)
Conditional
Required for platform:admin callers. Workspace-scoped admins use their own workspace by default.
status
string
No
Filter by grant status (pending_entity, pending_verification, active, revoked).
limit
integer
No
Page size (1-20, default 20).
continuation_token
integer
No
Offset for pagination (default 0).
Responses:
200
Paginated list of grants.
403
Missing admin scope.
Results are ordered newest first with stable ordering across pages.
Get a Provider Access Grant
GET /admin/scribe/grant/{grant_id}
Retrieve a single provider access grant by ID. Returns metadata only.
Path parameters:
grant_id
string (UUID)
The grant's unique identifier.
Query parameters:
workspace_id
string (UUID)
Conditional
Required for platform:admin callers.
Responses:
200
Grant detail.
404
Grant not found in the target workspace.
Revoke a Provider Access Grant
POST /admin/scribe/grant/{grant_id}/revoke
Revoke a provider access grant (soft delete). This immediately blocks both new human provider logins and new machine-to-machine act-as-by-email token mints that resolve against the grant. Any active sessions and refresh tokens bound to the grant are also revoked, so already-issued human sessions stop working. Short-lived machine-to-machine tokens expire within their normal time-to-live.
Access can be restored by re-inviting the same email, which creates a new grant.
Path parameters:
grant_id
string (UUID)
The grant's unique identifier.
Query parameters:
workspace_id
string (UUID)
Conditional
Required for platform:admin callers.
Responses:
200
Grant revoked. Returns the updated grant object.
404
Grant not found in the target workspace.
Grant Response Object
id
string (UUID)
Unique grant identifier.
workspace_id
string (UUID)
Workspace the grant belongs to.
provider_entity_id
string (UUID) or null
Bound provider entity, if any.
email
string
Provider's email address.
email_verified_at
string (datetime) or null
When the email was verified.
status
string
Current lifecycle status.
role
string
provider or scribe_admin.
scopes
array of strings
Scopes conferred by the grant's role.
requires_mfa
boolean
Whether MFA is required.
granted_by_entity_id
string (UUID)
Entity that created the grant.
granted_at
string (datetime)
When the grant was created.
revoked_at
string (datetime) or null
When the grant was revoked, if applicable.
revoked_by_entity_id
string (UUID) or null
Entity that revoked the grant, if applicable.
Last updated
Was this helpful?