{
  "schema": "aaes/capability-pack/1",
  "provider": "genesys",
  "version": "1.0.0",
  "description": "Read Genesys users, active user conversations, queues, and conversation analytics; join or unjoin existing queue members, place outbound calls, and delete users. Uses the customer's regional API; conversation reads and calls need a separate user-context token.",
  "notes": "Review status: on 2026-09-23, every registered endpoint, method, operation ID, summary, and OAuth scope was checked against Genesys's first-party swagger reference. The API host's /api/v2/docs/swagger route redirects to Genesys's publicapi-v2-latest.json schema on its own public S3 host, the source used by the Developer Center's API explorer.\n\nThe pack was initially based on official SDK repositories because the JavaScript-only Developer Center reference could not be extracted, and the /api/v2/docs/swagger.json route returned 404. The later first-party schema review resolved that reference-access gap.\n\nDeployment obligations, not review gaps: the owners are placeholders the deployment replaces with accountable humans, the reserved host below must be substituted before enabling, and the unverified token-revocation cut-off named in the credential note is a deployment-time verification item this pack claims nothing about.\n\nThe endpoint host 'genesys-cloud.invalid' is a reserved non-production placeholder (an RFC 2606 reserved TLD): Genesys Cloud hosts are region-specific (the official SDK documents base paths such as https://api.mypurecloud.com, https://api.mypurecloud.jp and per-region login hosts for token issuance), so substitute the customer's regional API host before enabling, in every endpoint, in the resource locators and in every egress allowlist entry — the allowlist matches exactly, so all three must be substituted together, and substitution is a required deployment step.\n\nExternal token issuance: an external deployment process exchanges the OAuth client's client id and client secret at the region's login host for an access token and stores and renews the complete header value described in the credential note; storing the client credentials themselves under the reference does not make the HTTP injector perform OAuth — the injector injects the stored value verbatim.\n\nApproval classification: conversations.calls.create places a live outbound voice call to an end recipient — a message delivered to a person — so it is registered as create and send at the minimum R3 tier; send is one of the designated actions requiring human approval. The analytics capability registers as read even though the vendor method is POST: the Genesys analytics query endpoints accept a query body and return data without mutating state, so the governed effect is a read.\n\nDocumented exclusions — this pack does not register: authorization administration (creating roles or divisions, assigning roles to users — privilege-granting mutations of the access-control plane itself); OAuth client management (creating or deleting the very clients that mint tokens); Architect flow publishing and check-in (a deploy of routing logic to production); conversation recording deletions and recording-policy changes (erasure of compliance records); telephony and trunk configuration; organization and WFM administration; external-contacts bulk import and bulk delete; and the notification/WebSocket channels — each is a different registration requiring its own review, and none is approximated here.",
  "credential": {
    "secret_ref_id": "secret-ref-genesys-client-credentials-token",
    "custody": "customer_vault",
    "inject": "header",
    "inject_name": "Authorization",
    "note": "Store a complete 'Bearer <access_token>' header value in the client's secret manager. For the pack-level reference, an administrator creates a Client Credentials OAuth client under Admin > Integrations > OAuth and assigns minimal roles and divisions. An external process exchanges its ID and secret at the customer's regional login host, then stores and renews the token. The executor injects the value unchanged; AuthorizeClientCredentials is a Genesys SDK helper for that external process, not the executor.\n\nRead the client's actual token duration. The documented range is 300–172,800 seconds (maximum two days, default 86,400). A client holding only the SCIM Integration role can extend it to 38,880,000 seconds (450 days). HIPAA-enabled organizations impose a 15-minute idle timeout on OAuth-client tokens. Refresh before expiry; an expired value fails closed.\n\nDisabling or deleting the OAuth client stops new issuance, but the reviewed material does not establish immediate invalidation of existing tokens. The client-management documentation says clients under 30 days are deleted irreversibly, older clients deactivate for seven days, and applications using deleted credentials lose access. It does not establish the residual validity window for issued tokens. Treat them as valid until expiry unless the deployment verifies cut-off with Genesys; review that behavior before enabling.\n\nTwo capabilities need a separate reference, secret-ref-genesys-user-context-token: genesys.conversations.read and genesys.conversations.calls.create. These operations act in user context; more roles on a Client Credentials token do not supply it.\n\nThat reference stores the complete 'Bearer <access_token>' header minted externally through a user-context OAuth grant, such as authorization code or implicit, at the regional login host for a dedicated user. The external process owns the grant and refresh. Calls additionally require an assigned, provisioned station and an active user session; verify those platform prerequisites before enabling.\n\nKeep each token only in executor memory for a call, never in logs, traces, diagnostics, or crash dumps. Do not enable the pack if the deployment cannot meet those requirements."
  },
  "capabilities": [
    {
      "capability_id": "genesys.users.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "genesys-cloud.invalid"
      ],
      "endpoint": "https://genesys-cloud.invalid/api/v2/users",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-genesys-client-credentials-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "genesys-org-users",
      "description": "List the org's users from the collection endpoint: directory profiles with names and contact details, which are personal data. The registered path covers the collection read only — single-user reads (GET /api/v2/users/{userId}) are not registered by this pack.\n\nThe host is a reserved placeholder: substitute the customer's regional API host before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "genesys.conversations.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "genesys-cloud.invalid"
      ],
      "endpoint": "https://genesys-cloud.invalid/api/v2/conversations",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-genesys-user-context-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "genesys-org-conversations",
      "description": "List the authenticated user's active conversations, not all conversations in the organization. This requires the separate user-context OAuth reference in the credential note; adding roles to the pack's client-credentials token does not provide user context. Conversation records include customer identifiers, addresses, and participants and are classified as pii (personal data).\n\nSingle-conversation reads (GET /api/v2/conversations/{conversationId}) are not registered. Replace the reserved host with the customer's regional API host before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "genesys.queues.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "genesys-cloud.invalid"
      ],
      "endpoint": "https://genesys-cloud.invalid/api/v2/routing/queues",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-genesys-client-credentials-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "genesys-org-routing",
      "description": "List routing queues from the collection endpoint: queue names and configuration, which reveal contact-center structure and are classified as internal data. The registered path covers the collection read only.\n\nThe host is a reserved placeholder: substitute the customer's regional API host before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "genesys.analytics.conversations.query",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "genesys-cloud.invalid"
      ],
      "endpoint": "https://genesys-cloud.invalid/api/v2/analytics/conversations/details/query",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-genesys-client-credentials-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "genesys-org-conversations",
      "description": "Run a conversation-details analytics query. The vendor method is POST because the query is supplied as a request body, but the operation returns analytics data and mutates nothing, so the governed effect is registered as read.\n\nThe request body is unrestricted — the caller chooses filters, interval and metrics — and conversation detail records contain customer and agent data, so the capability registers at the pii class.\n\nThe host is a reserved placeholder: substitute the customer's regional API host before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "genesys.queues.members.update",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R2",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "genesys-cloud.invalid"
      ],
      "endpoint": "https://genesys-cloud.invalid/api/v2/routing/queues/QUEUE_ID/members",
      "method": "PATCH",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-genesys-client-credentials-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "update"
      ],
      "resource_id": "genesys-org-users",
      "description": "Join or unjoin up to 100 existing members of one queue. This changes whether members are joined to the queue; it does not add or remove membership. Genesys disregards user-queue pairs that are not already members and processes the update asynchronously, so the response may not show the final state.\n\nThe request may carry any member updates allowed by the OAuth client's roles; this registration does not limit the member list. Named users make this pii (personal data). Bind QUEUE_ID and replace the reserved host before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "genesys.conversations.calls.create",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "genesys-cloud.invalid"
      ],
      "endpoint": "https://genesys-cloud.invalid/api/v2/conversations/calls",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-genesys-user-context-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "create",
        "send"
      ],
      "resource_id": "genesys-org-conversations",
      "description": "Place an outbound voice call as the authenticated user: according to the reviewed vendor-generated SDK documentation, POST /api/v2/conversations/calls creates a call conversation in user context, so this capability overrides the pack-level client-credentials reference with the separately documented user-context OAuth reference described in the credential note, and the user must meet the platform's station and session prerequisites for placing calls. The effect rings a telephone number and opens a live voice interaction with an end recipient, and the recipient may receive the call before any cancellation.\n\nThe capability is therefore registered as create and send at the minimum R3 tier — send is one of the designated actions requiring human approval.\n\nOn supported AAES-mediated execution paths, irreversible actions require approval by an authorized person; this does not prevent calls through bypass or observation-only paths.\n\nThe request body is unrestricted: the caller supplies the destination number, so the vendor verb being 'create' does not lower the effect. The dialed number is personal data.\n\nThe host is a reserved placeholder: substitute the customer's regional API host before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "genesys.users.delete",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "genesys-cloud.invalid"
      ],
      "endpoint": "https://genesys-cloud.invalid/api/v2/users/USER_ID",
      "method": "DELETE",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-genesys-client-credentials-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "delete"
      ],
      "resource_id": "genesys-org-users",
      "description": "Delete a user from the org. Delete is one of the designated actions requiring human approval; Genesys documents that deleting a user deactivates the account so the person can no longer log in and removes every permission assigned to them. The user's email address, performance data, conversation and chat history, files stored in Documents and voicemails are retained, and are removable only through the GDPR API. A deleted user can be restored to active status, but roles, permissions, extensions and default stations are not reassigned, and a user who was in a custom division comes back in the Home division; a user deleted through the GDPR API cannot be restored. This pack therefore makes no reversibility claim. USER_ID is a placeholder the deployment binds to a concrete user before enabling, and the host is a reserved placeholder to substitute before enabling.",
      "requires_review": true
    }
  ],
  "resources": [
    {
      "resource_id": "genesys-org-users",
      "kind": "api",
      "locator": "https://genesys-cloud.invalid/api/v2/users",
      "data_class": "pii",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    },
    {
      "resource_id": "genesys-org-conversations",
      "kind": "api",
      "locator": "https://genesys-cloud.invalid/api/v2/conversations",
      "data_class": "pii",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    },
    {
      "resource_id": "genesys-org-routing",
      "kind": "api",
      "locator": "https://genesys-cloud.invalid/api/v2/routing/queues",
      "data_class": "internal",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    }
  ],
  "review": {
    "state": "library",
    "date": "2026-10-22",
    "sources": [
      "https://github.com/MyPureCloud/platform-client-sdk-go (retrieved 2026-09-21)",
      "https://pkg.go.dev/github.com/mypurecloud/platform-client-sdk-go/v157/platformclientv2 (retrieved 2026-09-21)",
      "https://raw.githubusercontent.com/MyPureCloud/platform-client-sdk-go/master/platformclientv2/conversationsapi.go (retrieved 2026-09-21)",
      "https://raw.githubusercontent.com/MyPureCloud/platform-client-sdk-go/master/platformclientv2/routingapi.go (retrieved 2026-09-21)",
      "https://api.mypurecloud.com/api/v2/docs/swagger (retrieved 2026-09-23)",
      "https://help.genesys.cloud/articles/create-an-oauth-client/ (retrieved 2026-09-23)",
      "https://help.genesys.cloud/articles/view-edit-or-delete-oauth-clients-in-your-organization/ (retrieved 2026-09-23)",
      "https://help.genesys.cloud/articles/authorize-an-oauth-client-2/ (retrieved 2026-09-23)",
      "https://help.genesys.cloud/faqs/what-happens-when-i-delete-a-users-account/ (retrieved 2026-10-22)",
      "https://help.genesys.cloud/faqs/what-happens-when-i-restore-a-users-account/ (retrieved 2026-10-22)"
    ],
    "reviewer_id": "owner-delegated"
  }
}