Agent Identity Security API Reference

Use the Agent Identity Security REST API to programmatically discover agents, query posture issues, audit MCP servers, and retrieve compliance status across your tenant.

Base URL

All API paths are relative to the following base URL:

https://<tenant-host>/api/v1

Replace <tenant-host> with your tenant's hostname as described in the Tenant URL section below.

Prerequisites

Every Agent Identity Security API request requires three pieces of information: a Tenant URL, a Subdomain, and a Bearer Token. Make sure you have all three before making your first API call.

Tenant URL

What it is: The base HTTPS URL of your Agent Identity Security deployment. All API paths are appended to this URL.

Table 1. Tenant URL Formats by Deployment Mode
Deployment Mode Tenant URL Format Example
SaaS (Cloud) https://<subdomain>.<tenant-host> https://acme.<tenant-host>
On-Premises https://<hostname>:<port> https://ais.company.com:443
How to get it: Provided by your Agent Identity Security administrator at onboarding. You can also find it in the browser address bar when logged into the Agent Identity Security dashboard.

Subdomain (X-Tenant-Subdomain Header)

What it is: Your tenant's unique identifier, sent as the X-Tenant-Subdomain request header on every API call.

Example: If your tenant URL is https://acme.<tenant-host>, the subdomain is acme.

How to get it: The subdomain is the first segment of your tenant URL after https://. Contact your Agent Identity Security administrator if you are unsure it is set during tenant provisioning.

Bearer Token (Authorization Header)

What it is: A short-lived JSON Web Token (JWT) passed as Authorization: Bearer <token>. Tokens expire after approximately 15 minutes; you must re-authenticate to obtain a new one.

How to get it: Log in via the Agent Identity Security UI, or call the login API directly:
POST https://<tenant-host>/api/v1/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "yourpassword",
  "is_local_login": true
}
The response includes an access_token copy this value and use it as your Bearer token:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 900
}

Putting It All Together

The example below shows a complete API call with all three credentials annotated:

curl -i -X GET \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6..." \  # ← from POST /auth/login
  -H "X-Tenant-Subdomain: <your-subdomain>" \               # ← your tenant subdomain
  -H "Accept: application/json" \
  'https://<tenant-host>/api/v1/posture/compliance/agents?compliant=false&severity=critical'
#   └── Tenant URL ─────────────────────────────────────────────────────────────────────────┘

Prerequisites Summary

Table 2. Required Credentials at a Glance
Credential Used As How to Obtain
Tenant URL Base of every API URL, e.g. https://acme.<tenant-host> Agent Identity Security admin email / browser address bar after login
Subdomain X-Tenant-Subdomain: <value> request header on every call First segment of your tenant URL (ask your Agent Identity Security admin if unsure)
Bearer Token Authorization: Bearer <token> request header on every call POST /api/v1/auth/login with email + password → copy access_token
Agent Identity Security Account Required to generate a Bearer Token Provisioned by your Agent Identity Security administrator

APIs Covered