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`

Grants access to a user by email for a private Genie. If the email matches an existing HelpGenie account, the user is added to the Genie’s direct-access list immediately.

string

required

Genie UUID to grant access to.

string

required

Email address of the person to grant access.

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

`invite`

Sends email invitations to a batch of addresses. Each recipient gets a unique, one-use access link. If the email matches an existing HelpGenie account, that user is also added directly to the Genie’s access list. Up to 50 emails per call.

string

required

Genie UUID to invite people to.

string[]

required

List of email addresses to invite. Maximum 50. Invalid or duplicate addresses are silently ignored.

string

ISO 8601 expiry datetime for the access links. Omit for links that never expire.

string

Optional idempotency key for the invite batch. If omitted, one is generated automatically. Re-sending with the same campaignId skips already-delivered addresses.

Response

{
  "campaignId": "campaign-uuid",
  "invited": [
    { "email": "user@example.com", "sent": true, "deliveredNow": true, "state": "sent" }
  ]
}

Each item in invited contains the email, whether the message was sent in this request (deliveredNow), and a state of "sent", "skipped" (already delivered), or "unknown" (delivery state unconfirmed).

`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.

string

required

Genie UUID.

string

required

User UUID whose access to update.

string

New expiry datetime (ISO 8601), 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.

string

required

Genie UUID.

string

required

User UUID to revoke access for.

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 direct-access list.

string

required

Access request ID (numeric, from the requests action).

string

required

"approved" or "denied".

string

Expiry for the granted access (approval only). Omit for permanent access.

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`

`invite`

`update`

`delete`

`update-user`

`delete-user`

`requests`

`resolve`

Error codes

​Actions

​all

​list

​list-team-access

​create

​invite

​update

​delete

​update-user

​delete-user

​requests

​resolve

​Error codes

Actions

`all`

`list`

`list-team-access`

`create`

`invite`

`update`

`delete`

`update-user`

`delete-user`

`requests`

`resolve`

Error codes