Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.airmdr.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Purpose

The BeyondTrust integration enables AirMDR to connect with BeyondTrust APIs and retrieve relevant access, session, audit, and security event information. This helps SOC teams investigate privileged access activity, correlate incidents, and automate response actions from AirMDR playbooks.

​
Supported Versions

ComponentSupported Version
BeyondTrust Remote SupportSupported
BeyondTrust Privileged Remote Access (PRA)Supported
BeyondTrust BeyondInsightSupported
BeyondTrust Password SafeSupported
Deployment ModelsCloud & On-Premises
Authentication MethodOAuth 2.0
AirMDR Integration TypeAPI-Based
Menu names may vary slightly depending on your BeyondTrust deployment version.

​
Authentication

AirMDR uses OAuth 2.0 authentication to securely connect to BeyondTrust APIs.
CredentialDescription
Base URLBeyondTrust tenant URL or appliance URLhttps://company.beyondtrustcloud.com
OAuth Client IDUnique client identifier generated for the API accounte52a9aa6*****3a40601a736b230a1bebcd1
OAuth Client SecretAPI Client Secret generated for the API account***************

​
Role-Based Access Considerations

  • Create a dedicated API account specifically for AirMDR.
  • Follow the Principle of Least Privilege.
  • Avoid using personal administrator accounts.
  • Periodically rotate OAuth credentials.
  • Store secrets securely.

​
BeyondTrust Integration Setup Steps

1

Log in to BeyondTrust Admin Console

  1. Open a supported browser.
  2. Go to the BeyondTrust admin URL: https://<your-beyondtrust-domain>/login
  3. Sign in with an administrator account.
    Admin privileges are required to create or edit API accounts.
2

Identify the Base URL

  1. In the browser address bar, copy the BeyondTrust domain.
  2. Remove /login from the URL.
  3. Use the remaining value as the Base URL.
    Example:
    Login URL: https://company.beyondtrustcloud.com/login
    Base URL: https://company.beyondtrustcloud.com
    Use this Base URL while configuring the BeyondTrust integration in AirMDR.
3

Open API Configuration

  1. From the left navigation menu, select Management.
  2. Open the API Configuration tab.
  3. Confirm that API access is enabled.
    For Remote Support or Privileged Remote Access deployments, ensure the required API options are enabled based on the AirMDR use case.
    If API access is disabled, AirMDR cannot authenticate or retrieve data from BeyondTrust.
4

Create a New API Account

  1. In API Configuration, click Add or Create New API Account.
  2. Enter a clear account name. For Example: AirMDR Integration API Account.
  3. Enable the API account.
  4. Select the required API permissions.
  5. Avoid selecting full access unless it is explicitly required and approved.
  6. Click Save.
5

Copy the OAuth Client ID

  1. Open the newly created API account.
  2. Locate the OAuth Client ID field.
  3. Copy the value.
  4. Store it securely for AirMDR configuration.
    **Example: **
    OAuth Client ID:
    <generated-client-id>
6

Generate the OAuth Client Secret

  1. In the same API account screen, click Generate New Client Secret.
  2. Copy the generated secret immediately.
  3. Store the secret in an approved password vault or secret manager.
  4. Click Save.
The OAuth Client Secret may be visible only once. If it is lost, generate a new client secret and update the AirMDR integration.

​
Integration Credential Requirements

Use the following values in the AirMDR integration configuration screen:
AirMDR FieldBeyondTrust ValueDescription
Base URLBeyondTrust Instance URLThe root URL of your BeyondTrust tenant or appliance. Example: https://company.beyondtrustcloud.com
OAuth Client IDOAuth Client IDThe unique identifier generated for the BeyondTrust API account.
OAuth Client SecretOAuth Client SecretThe secret generated for the BeyondTrust API account and used for OAuth authentication.

​
Where to Obtain These Credentials

CredentialLocation in BeyondTrust
Base URLBrowser address bar after logging in to BeyondTrust (remove /login if present).
OAuth Client IDManagement → API Configuration → API Account → OAuth Client ID
OAuth Client SecretManagement → API Configuration → API Account → Generate New Client Secret
The OAuth Client Secret may only be displayed once when generated. Store it securely in a password vault or secret management solution before proceeding with the AirMDR configuration.

​
Validate Connectivity

Use the following command to verify connectivity and token authentication: 
curl -X POST "https://company.beyondtrustcloud.com/oauth2/token" \
-H "Authorization: Basic <Base64_ClientID_ClientSecret>" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials"
“access_token”: “eyJhbGciOiJIUzI1NiIs…”,“token_type”: “Bearer”,“expires_in”: 3600

​
Configure BeyondTrust in AirMDR Integrations Dashboard

  1. Navigate to AirMDR, provide the credentials and click Login
  2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select Integrations.
  3. Use the search option, enter the keyword “Gravwell”, select the Connections tab, and click + Create button.
  4. Enter an unique name to the Instance (e.g., your org name-Gravwell) to easily identify the user connection by AirMDR.
  5. Enter the application credentials like Instance URL and Token in the Authentication Details field params, and click Save.

​
Skills provided by this Integration

Skill IDPurpose
Get Gravwell Ingesters stateGet the state of ingesters in gravwell instance.
Gravwell Execute Query for DetectionsThis skill executes queries on Gravwell instances for detection purposes. It supports custom search strings and time duration filters to retrieve security logs and events for analysis.
Execute Gravwell QueryExecute a query in Gravwell.
To view the details of Input Parameters and Output for the respective skills
  • Go to AirMDR → Gravwell Integration page.
  • Select the Skills tab and click on the required listed skills.

​
Additional Information

ErrorPossible CauseResolution
401 UnauthorizedInvalid, expired, or copied incorrectly tokenGenerate a new token and update AirMDR.
403 ForbiddenToken does not have required permissionsAdd required search/read permissions.
404 Not FoundIncorrect Instance URL or API pathVerify the base URL and endpoint.
TLS certificate errorSelf-signed or untrusted certificateUse a trusted certificate or configure certificate validation as per internal policy.
Connection timeoutNetwork/firewall issueCheck connectivity from AirMDR or remote agent.
Query parse failedInvalid Gravwell query syntaxValidate query in Gravwell UI first.
No data returnedIncorrect tag, time range, or permission issueConfirm tag access and query scope.

​
Where to Check

LocationPurpose
AirMDR Integration StatusValidate connection status and integration health.
AirMDR Playbook Execution LogsReview API call failures or query errors.
Gravwell API Token PageCheck token status and expiration.
Gravwell Webserver LogsTroubleshoot authentication or API errors.
Sample Success Log
INFO Gravwell integration validation completed successfully.INFO Tags retrieved from Gravwell instance.Sample Failure LogERROR Gravwell API request failed.ERROR Status Code: 401 Unauthorized.ERROR Reason: Invalid or expired token.\Recommended Log Levels
Log LevelUsage
INFOSuccessful connection, validation, and query execution.
WARNSlow response, partial data, or expiring token.
ERRORAuthentication failure, timeout, SSL failure, or invalid endpoint.
DEBUGUse temporarily during troubleshooting only.

​
Do

  1. Use a dedicated Gravwell token for AirMDR.
  2. Grant only required permissions.
  3. Set token expiration where possible.
  4. Store the token in a secure vault.
  5. Use HTTPS with valid TLS certificates.
  6. Rotate tokens periodically.
  7. Disable or delete unused tokens.
  8. Use a remote agent when Gravwell is not publicly reachable.

​
Avoid

  1. Do not use personal admin tokens for integrations.
  2. Do not share tokens over email or chat.
  3. Do not disable SSL verification unless approved internally.
  4. Do not grant token write permissions unless absolutely required.
  5. Do not reuse the same token across multiple tools.
  • 📧 Contact AirMDR Support through your designated support channel.
  • 🔁 Rotate credentials regularly. Recommended cadence: Every 90 days or as per internal security policy
  • 🔄 Reconnect in AirMDR when secrets are changed.
ActivityRecommended Frequency
Review token permissionsQuarterly
Rotate API tokenAs per company security policy
Check token expirationMonthly
Validate integration healthAfter Gravwell upgrades
Review AirMDR execution logsDuring incident or integration failures

​
Data Exchanged

Data TypeDirectionDescription
API TokenAirMDR → GravwellUsed for authentication.
Search QueryAirMDR → GravwellUsed to retrieve required telemetry.
AlertsGravwell → AirMDRReturned if alert read access is configured.
Tags / Telemetry MetadataGravwell → AirMDRUsed to identify available data sources.
Search ResultsGravwell → AirMDRUsed for enrichment and investigation.

​
Ports and Endpoints\

ItemValue
ProtocolHTTPS
Default Port443
Instance URL Formathttps://<gravwell-hostname>
Example API Endpoint/api/tags
Search Parse Endpoint/api/parse
Direct Search Endpoint/api/search/direct
Use HTTPS with a valid TLS certificate wherever possible.

\