Authenticating with AI Assistant API

The Global Relay AI Assistant API provides machine authentication, allowing your automated system to access information in Global Relay that can be used by your downstream tools.

Machine authentication uses a backend system to make HTTP calls with a bearer token. It allows a machine, i.e. your automated system, to authorize itself using OAuth 2.0 Client credentials, so it can:

  • Submit natural language questions to Global Relay AI Assistant.
  • Receive AI-generated answers based on your archived communications.
  • Deliver these responses and citations to related communications via the API.

Machine authentication maps a machine to a specific user ID in Global Relay Service Manager, allowing your machine to effectively inherit Global Relay Archive/Function roles and message access for use with the AI Assistant API.

Understanding machine access

A machine is limited to entitlements and access rights defined in Service Manager: it can only take actions that the mapped user can within the assigned Archive and Function. For example, if the user can access only their messages, your machine can also only access the user’s own messages.

When an automated system, i.e. machine, submits a prompt, a user ID is passed to Global Relay Archive, so the machine can act on that user’s behalf.

A machine can ask natural-language questions, search the defined archived data the mapped user can access, and receive AI-generated answers with citations. This information, available via API, can be programmatically exported or used by an external application, such as an outside compliance or legal tool.

A machine is limited by the capabilities of Global Relay AI Assistant, so the machine cannot run open-ended searches or export messages in bulk.

Use cases

The machine authentication model was designed to support the following use cases:

Legal and eDiscovery investigation

Your legal team may use an eDiscovery review tool while Global Relay Archive holds your record-keeping, source-of-truth data.

When your team needs to produce data for litigation or a regulatory response, your machine, i.e. your integration layer with the review tool, can authenticate with the AI Assistant API, using OAuth 2.0 Client Credentials, while mapped to a specific Global Relay user and their defined access rights.

The machine submits prompts to search and identify relevant messages, receives AI-generated responses with source references, and imports the cited messages into your eDiscovery review tool.

Your organization must then determine which users can access data imported from AI Assistant.

Compliance surveillance

When a compliance team uses Global Relay Archive policies to flag messages for supervised users, they may need to investigate those messages within their own compliance tools.

Your machine integration can authenticate with the AI Assistant API using OAuth 2.0 Client Credentials while mapped to a Global Relay user with compliance-appropriate access, e.g. supervised users’ messages, classification tags, and metadata viewer roles. When a Global Relay Archive policy flags a message, your machine-integrated compliance application can submit a question, e.g. “Summarize the communications flagged by policy [X] for supervised user [Y] during [date range]” to receive an AI-generated answer with source references.

As a result, your machine can create a case for the investigation in your third-party system, import the relevant messages from Global Relay, and assign them for human review.

Automated business systems

When a risk, compliance, or legal operations team needs archived communication information for internal dashboards, audit reports, or downstream workflows on a recurring basis, they can run a fully automated process using this API.  

Your machine submits prompts on a schedule or specific action, receives AI-generated responses with source references, and feeds the results into your downstream system, including recurring retrospective reviews, daily risk evaluations, etc.

Supported platforms, tools, and systems

The following table provides examples of platforms supported by machine authentication:

PlatformHow machine authentication is used
eDiscovery platformsAutomated import of messages for legal review
Compliance surveillance systemsAutomated investigation pipelines that query the Archive on a schedule or specific actions
Automated business system, e.g. custom scripts and batch jobsNightly risk question runs, recurring retrospective reviews, dashboard data feeds
Developer toolsTools typically using API keys rather than OAuth browser redirect, which are better suited to machine credentials than the human authorization
Any backend systemAny system that can make HTTP calls with a bearer token

Setting up machine authentication

To set up machine authentication, the following steps occur:

  1. A Global Relay administrator creates an API Access Instance in Global Relay Service Manager.
  2. Service Manager calls a backend service to generate a client ID and secret.
    Note: When authenticating with the client ID and secret, an API Access User receives an access bearer token, valid for 24 hours. A new token must be generated once every 24 hours.
  3. The client ID is mapped to an API Access User in Service Manager.
  4. The user is assigned a role, with specific message access, in the relevant Archive/Function and the AI Assistant API entitlement.
  5. The Global Relay administrator delivers the credential to your administrator to be configured in your system.

If you lose your client secret, it cannot be recovered. Your Global Relay administrator must issue a new secret for the same client ID.

The Global Relay AI Assistant API is a standalone service with its own entitlement, separate from Global Relay AI Assistant users access in Global Relay Portal or Global Relay App.

How machine authentication works

  1. Obtain client credentials: Your system obtains its client credentials (i.e. client ID and secret) through Global Relay.
  2. Acquire a bearer token: Your system calls the Global Relay Authentication Service API at https://iam-oauth2.globalrelay.com/oauth2/token with its client credentials to receive a bearer (access) token.
    The request must include the following parameters:
    • grant_type = client_credentials
    • audience = https://ai.api.globalrelay.com
    • scope = aiassistantapi
      The returned bearer token is used to authenticate subsequent calls to the AI Assistant API.
  3. Send API requests: Your system includes the bearer token in the Authorization header on every API call to the applicable AI Assistant API endpoint, i.e. https://ai.api.globalrelay.com/v1/* This token is valid for 24 hours.
  4. Token validation: Global Relay validates the token. Your system needs to call Global Relay Authentication Service API once every 24 hours to refresh the token.
    If the token is valid, the request passes through to the AI Assistant API with the client ID.
    If the token is invalid or expired, the request results in an error.
  5. Client ID matching: The AI Assistant API calls the Global Relay Service Manager API endpoint, using the client ID, to match it against the API Access User ID.
  6. Access control enforcement: The AI Assistant API passes the API Access User ID to Global Relay Archive, where access controls are enforced the same as for user access. Queries only return data based on the mapped user’s entitlements and access rights.