> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpgenie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Genie Access

> Manage access control for private Genies — create shareable access links, grant direct user access, and handle inbound access requests.

Genie Access gives you fine-grained control over who can interact with a private Genie. Access is tracked in two ways:

* **Access grants** — tokenised links with optional use-count limits and expiry dates, shareable with anyone.
* **Agent users** — direct per-user access records tied to a specific HelpGenie account.

When a visitor requests access to a private Genie, an `agent_access_requests` record is created and the Genie owner can approve or deny it via `resolve`.

***

## Actions

### `all`

Returns all users who have been granted direct access to a Genie.

**Parameters**

| Field | Type   | Required | Description                       |
| ----- | ------ | -------- | --------------------------------- |
| `id`  | string | Yes      | Genie UUID (passed as request ID) |

**Response**

```json theme={null}
{
  "users": [
    {
      "agent_id": "agent-uuid",
      "user_id": "user-uuid",
      "granted_by": "owner-uuid",
      "expires_at": null,
      "created_at": "2024-01-01T00:00:00Z",
      "profile": { "id": "user-uuid", "full_name": "Jane Doe", "email": "jane@example.com", "avatar_url": null }
    }
  ]
}
```

***

### `list`

Returns access grant links (token-based access, not per-user). When no Genie is specified, returns grants for all genies you own.

**Parameters**

| Field          | Type   | Required | Description                                                       |
| -------------- | ------ | -------- | ----------------------------------------------------------------- |
| `id`           | string | No       | Genie UUID (passed as request ID). Filters results to this genie. |
| `data.agentId` | string | No       | Alternative to `id` — Genie UUID passed in the request body.      |

When neither `id` nor `data.agentId` is provided, non-admin users receive grants for all genies they own. Admin users receive all grants across the platform.

**Response**

```json theme={null}
{
  "grants": [
    {
      "id": 1,
      "agent_id": "agent-uuid",
      "max_uses": 10,
      "use_count": 3,
      "expires_at": "2025-01-01T00:00:00Z",
      "last_used_at": "2024-06-01T00:00:00Z",
      "granted_by": "owner-uuid",
      "created_at": "2024-01-01T00:00:00Z",
      "label": "ab12cd",
      "token": "64-char-token"
    }
  ]
}
```

`token` is omitted for expired grants.

***

### `list-team-access`

Returns direct per-user access records for a Genie, with profile data for each user.

**Parameters**

| Field | Type   | Required | Description                       |
| ----- | ------ | -------- | --------------------------------- |
| `id`  | string | Yes      | Genie UUID (passed as request ID) |

**Response**

```json theme={null}
{
  "access": [
    {
      "agent_id": "agent-uuid",
      "user_id": "user-uuid",
      "granted_by": "owner-uuid",
      "expires_at": null,
      "created_at": "2024-01-01T00:00:00Z",
      "profile": { "id": "user-uuid", "full_name": "Jane Doe", "email": "jane@example.com", "avatar_url": null }
    }
  ]
}
```

***

### `create`

Creates a new access grant link for a Genie. Returns the full token (only shown once).

**Parameters**

| Field        | Type   | Required | Description                                                                 |
| ------------ | ------ | -------- | --------------------------------------------------------------------------- |
| `id`         | string | Yes      | Genie UUID (passed as request ID)                                           |
| `max_uses`   | number | No       | Maximum number of times the link can be used. `0` means unlimited (default) |
| `expires_at` | string | No       | ISO 8601 expiry datetime                                                    |

**Response** — `201`

```json theme={null}
{
  "grant": {
    "id": 1,
    "agent_id": "agent-uuid",
    "max_uses": 0,
    "use_count": 0,
    "expires_at": null,
    "granted_by": "owner-uuid",
    "created_at": "2024-01-01T00:00:00Z",
    "token": "64-char-token-shown-only-once"
  }
}
```

***

### `update`

Updates an existing access grant (use limit or expiry).

**Parameters**

| Field        | Type           | Required | Description                                     |
| ------------ | -------------- | -------- | ----------------------------------------------- |
| `id`         | string         | Yes      | Grant ID (numeric, passed as request ID)        |
| `max_uses`   | number         | No       | New maximum use count                           |
| `expires_at` | string \| null | No       | New expiry datetime, or `null` to remove expiry |

**Response**

```json theme={null}
{
  "grant": { /* updated grant row */ }
}
```

***

### `delete`

Deletes an access grant link. Anyone using the link after deletion will lose access.

**Parameters**

| Field | Type   | Required | Description                              |
| ----- | ------ | -------- | ---------------------------------------- |
| `id`  | string | Yes      | Grant ID (numeric, passed as request ID) |

**Response**

```json theme={null}
{ "deleted": true }
```

***

### `update-user`

Updates the expiry date for a specific user's direct access to a Genie.

**Parameters**

| Field        | Type           | Required | Description                                             |
| ------------ | -------------- | -------- | ------------------------------------------------------- |
| `agentId`    | string         | Yes      | Genie UUID                                              |
| `userId`     | string         | Yes      | User UUID                                               |
| `expires_at` | string \| null | No       | New expiry datetime, or `null` to make access permanent |

**Response**

```json theme={null}
{
  "agentUser": {
    "agent_id": "agent-uuid",
    "user_id": "user-uuid",
    "granted_by": "owner-uuid",
    "expires_at": "2025-01-01T00:00:00Z",
    "created_at": "2024-01-01T00:00:00Z"
  }
}
```

***

### `delete-user`

Revokes a specific user's direct access to a Genie.

**Parameters**

| Field     | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| `agentId` | string | Yes      | Genie UUID          |
| `userId`  | string | Yes      | User UUID to revoke |

**Response**

```json theme={null}
{ "deleted": true }
```

***

### `requests`

Returns all inbound access requests for a Genie (visitors who clicked "Request access").

**Parameters**

| Field | Type   | Required | Description                       |
| ----- | ------ | -------- | --------------------------------- |
| `id`  | string | Yes      | Genie UUID (passed as request ID) |

**Response**

```json theme={null}
{
  "requests": [
    {
      "id": "request-uuid",
      "agent_id": "agent-uuid",
      "email": "requester@example.com",
      "requested_at": "2024-01-01T00:00:00Z",
      "resolved_at": null,
      "solution": null,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

***

### `resolve`

Approves or denies an access request. On approval, the requester receives an email with an access link and (if they have a HelpGenie account) is added to the Genie's `agent_users`.

**Parameters**

| Field        | Type   | Required | Description                                   |
| ------------ | ------ | -------- | --------------------------------------------- |
| `requestId`  | string | Yes      | Access request UUID                           |
| `solution`   | string | Yes      | `"approved"` or `"denied"`                    |
| `expires_at` | string | No       | Expiry for the granted access (approval only) |

**Response**

```json theme={null}
{
  "resolved": true,
  "solution": "approved"
}
```

***

## Error codes

| Code               | Meaning                                                |
| ------------------ | ------------------------------------------------------ |
| `VALIDATION_ERROR` | Missing required parameter or request already resolved |
| `NOT_FOUND`        | Grant or access request not found                      |
| `FORBIDDEN`        | You do not own this Genie                              |
| `AGENT_NOT_FOUND`  | Genie does not exist                                   |
| `INTERNAL_ERROR`   | Unexpected server error                                |