Genie Access

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{ "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

{
  "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

{ "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

{
  "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

{
  "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

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

Actions

`all`

`list`

`list-team-access`

`create`

`update`

`delete`

`update-user`

`delete-user`

`requests`

`resolve`

Error codes

​Actions

​all

​list

​list-team-access

​create

​update

​delete

​update-user

​delete-user

​requests

​resolve

​Error codes

Actions

`all`

`list`

`list-team-access`

`create`

`update`

`delete`

`update-user`

`delete-user`

`requests`

`resolve`

Error codes