Skip to main content
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
FieldTypeRequiredDescription
idstringYesGenie 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 all access grant links for a Genie (token-based access, not per-user). Parameters
FieldTypeRequiredDescription
idstringYesGenie UUID (passed as request ID)
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
FieldTypeRequiredDescription
idstringYesGenie 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
FieldTypeRequiredDescription
idstringYesGenie UUID (passed as request ID)
max_usesnumberNoMaximum number of times the link can be used. 0 means unlimited (default)
expires_atstringNoISO 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
FieldTypeRequiredDescription
idstringYesGrant ID (numeric, passed as request ID)
max_usesnumberNoNew maximum use count
expires_atstring | nullNoNew 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
FieldTypeRequiredDescription
idstringYesGrant 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
FieldTypeRequiredDescription
agentIdstringYesGenie UUID
userIdstringYesUser UUID
expires_atstring | nullNoNew 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
FieldTypeRequiredDescription
agentIdstringYesGenie UUID
userIdstringYesUser UUID to revoke
Response 
{ "deleted": true }

​
requests

Returns all inbound access requests for a Genie (visitors who clicked “Request access”). Parameters
FieldTypeRequiredDescription
idstringYesGenie 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
FieldTypeRequiredDescription
requestIdstringYesAccess request UUID
solutionstringYes"approved" or "denied"
expires_atstringNoExpiry for the granted access (approval only)
Response 
{
  "resolved": true,
  "solution": "approved"
}

​
Error codes

CodeMeaning
VALIDATION_ERRORMissing required parameter or request already resolved
NOT_FOUNDGrant or access request not found
FORBIDDENYou do not own this Genie
AGENT_NOT_FOUNDGenie does not exist
INTERNAL_ERRORUnexpected server error