> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/platform-api/provider-access-grants.md).

# Provider Access Grants

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:

| Status                 | Meaning                                                                                                                                         |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `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:

| Role           | Description                                 |
| -------------- | ------------------------------------------- |
| `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:**

| Field                | Type           | Required | Description                                                                                                                        |
| -------------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `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:**

| Status | Description                                                              |
| ------ | ------------------------------------------------------------------------ |
| 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:**

| Parameter            | Type          | Required    | Description                                                                                        |
| -------------------- | ------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| `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:**

| Status | Description               |
| ------ | ------------------------- |
| 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:**

| Parameter  | Type          | Description                    |
| ---------- | ------------- | ------------------------------ |
| `grant_id` | string (UUID) | The grant's unique identifier. |

**Query parameters:**

| Parameter      | Type          | Required    | Description                            |
| -------------- | ------------- | ----------- | -------------------------------------- |
| `workspace_id` | string (UUID) | Conditional | Required for `platform:admin` callers. |

**Responses:**

| Status | Description                              |
| ------ | ---------------------------------------- |
| 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:**

| Parameter  | Type          | Description                    |
| ---------- | ------------- | ------------------------------ |
| `grant_id` | string (UUID) | The grant's unique identifier. |

**Query parameters:**

| Parameter      | Type          | Required    | Description                            |
| -------------- | ------------- | ----------- | -------------------------------------- |
| `workspace_id` | string (UUID) | Conditional | Required for `platform:admin` callers. |

**Responses:**

| Status | Description                                      |
| ------ | ------------------------------------------------ |
| 200    | Grant revoked. Returns the updated grant object. |
| 404    | Grant not found in the target workspace.         |

## Grant Response Object

| Field                  | Type                      | Description                                   |
| ---------------------- | ------------------------- | --------------------------------------------- |
| `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. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/platform-api/platform-api/provider-access-grants.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.