Introduction

The Admin API manages the resources that make up your AI Gateway organisation: the integrations that connect model providers, the credentials behind them, the configs and guardrails applied to workspaces, the policies that cap usage, the MCP servers you expose, and the analytics you report on. Anything an administrator sets up in Strata Cloud Manager can be set up here instead. Created in Strata Cloud Manager, the service account is the identity behind every administrative call. It exchanges its credentials for a short-lived token, the token names one tenant, and every request made with it lands on that tenant.

Admin API requests are authorised with a Strata Cloud Manager access token, not a gateway API key. A key that works for inference returns 401 here. See Authentication.

Your first request

Create a service account

In Strata Cloud Manager, go to System Settings > Identity & Access, select your tenant, and add an identity of type Service Account. Save the Client ID and Client Secret it issues, and note the tenant service group ID (TSG ID).Full walkthrough with roles and inheritance: Create a service account.

Request an access token

Exchange those three values for a token.

curl -d "grant_type=client_credentials&scope=tsg_id:<tsg_id>" \
  -u <client_id>:<client_secret> \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -X POST https://auth.apps.paloaltonetworks.com/oauth2/access_token

Call an endpoint

Send the token as a bearer token. Every endpoint takes the same header. Configs belong to a workspace, so name one with workspace_id, the workspace’s UUID.

curl "https://api.apps.paloaltonetworks.com/ai_gw/v2/configs?workspace_id=<workspace_uuid>" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The response lists the configs in that workspace. You don’t send a tenant identifier, because the token carries it. You do send the workspace, because the token is scoped to the whole organisation. Find a workspace’s ID shows how to get the UUID.

Refresh before it expires

Tokens last 15 minutes, reported as expires_in: 900 on the token response. Cache one for that window and refresh it shortly before it lapses.

Base URLs

Which base URL an endpoint uses follows the resource, not the sidebar group it sits in.

Base URL	Serves
`https://api.apps.paloaltonetworks.com/ai_gw/v2`	Configs, workspace guardrails, providers, API keys, usage and rate limit policies, MCP servers, analytics, feedback
`https://api.apps.paloaltonetworks.com/ai_gw/admin/v2`	Integrations, MCP integrations, secret references, deployments, organisation guardrails
`https://aigw.portkey.ai/v1`	`POST /logs` and `GET /logs/{logId}`. Self-hosted deployments substitute their own host
`https://api.sase.paloaltonetworks.com/airs/workspace/v1`	Workspaces: list, create, view and update the workspaces in a tenant

The organisation guardrail endpoints carry their prefix in the path instead of the base URL, as /admin/v2/guardrails against https://api.apps.paloaltonetworks.com/ai_gw. That resolves to the same place as the admin base above. Each endpoint’s reference page states its server. Where the two disagree, trust the reference page, which is generated from the specification.

How resources are scoped

Every resource sits at one of two levels. Knowing which one you are addressing explains most 403 responses.

Level	Addressed by	Holds
Organisation	The TSG ID inside your token. One TSG is one organisation.	Integrations, MCP integrations, secret references, deployments, organisation guardrails
Workspace	A `workspace_id` (the workspace UUID), passed explicitly	Configs, providers, workspace guardrails, analytics

The split matches the base URLs: organisation-level resources are served from the admin/v2 base. API keys and limit policies span both levels, and POST /api-keys/{sub-type} takes the level from the calling token rather than from the path — sub-type chooses user or service, nothing more. To reach a workspace-level resource, pass workspace_id as a query parameter, on every method, including POST and PUT. It’s required on these calls, and it must be the workspace’s UUID. A workspace slug doesn’t work here.

curl "https://api.apps.paloaltonetworks.com/ai_gw/v2/configs?workspace_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The Admin API takes an access token, and an access token is scoped to the whole organisation, so it can’t tell the gateway which workspace you mean. A workspace API key already belongs to one workspace, but the Admin API doesn’t accept those keys.

Find a workspace’s ID

The workspace UUID isn’t shown next to the slug in Strata Cloud Manager. Get it either of these ways:

From the API. GET /workspaces on the Workspace Service lists the workspaces in your tenant, with the same access token. Filter by name with exact_name, or with name for a case-insensitive substring match. Each workspace’s id is the value to pass as workspace_id.

curl "https://api.sase.paloaltonetworks.com/airs/workspace/v1/workspaces?exact_name=ML%20Platform%20Team" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "workspaces": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "ML Platform Team",
      "scope_name": "ml_platform_team_x7k2",
      "is_default": false,
      "status": "active"
    }
  ],
  "total_count": 1,
  "limit": 20,
  "offset": 0
}

The response is shortened here. Workspace names aren’t unique within a tenant, so check total_count before you take the first result.

From Strata Cloud Manager. Open the workspace and copy the UUID from the page URL.

Slugs and IDs

Mixing these up is a common cause of 404.

Slugs identify the resources you name yourself: /configs/{slug}, /integrations/{slug}, /providers/{slug}
IDs identify the resources the gateway names for you: /guardrails/{guardrailId}, /mcp-servers/{mcpServerId}, /policies/usage-limits/{policyUsageLimitsId}, /api-keys/{id}

Guardrails sit at both levels

/guardrails manages the guardrails of a single workspace. /admin/v2/guardrails manages the organisation-wide ones, which apply to every workspace unless a workspace is explicitly excluded. See Enforcing Org Level Guardrails.

Common tasks

Each of these is a sequence of calls, not a single endpoint.

Connect a model provider and provision it to a team

POST /integrations creates the integration and attaches the provider credential
PUT /integrations/{slug}/models chooses which models it exposes
PUT /integrations/{slug}/workspaces grants the workspaces that may use it

Steps 2 and 3 are model provisioning and workspace provisioning. Skip them and the integration exists but nobody can reach it.

Put an MCP server behind the gateway

POST /mcp-servers registers the server
GET /mcp-servers/{mcpServerId}/capabilities reads the tools it advertises
PUT /mcp-servers/{mcpServerId}/capabilities enables only the tools you intend to expose
PUT /mcp-servers/{mcpServerId}/user-access decides who may call it
POST /mcp-servers/{mcpServerId}/test confirms the connection before anyone depends on it

See the MCP Gateway documentation for what each capability means.

Cap what a team can spend

POST /policies/usage-limits defines the budget
GET /policies/usage-limits/{policyUsageLimitsId}/entities shows what the policy currently binds to
PUT /policies/usage-limits/{policyUsageLimitsId}/entities/{entityId}/reset clears consumption for one entity

Rate limits work the same way under /policies/rate-limits. Background in Budget Limits and Rate Limits.

Issue and rotate an API key

POST /api-keys/{sub-type} creates the key with the scopes it needs, user or service
POST /api-keys/{id}/rotate rotates it on a schedule or on suspicion

Available scopes are listed in API Keys (AuthN and AuthZ).

Report on last month

GET /analytics/graphs/cost returns spend over time
GET /analytics/groups/ai-models breaks it down by model
GET /analytics/groups/metadata/{metadataKey} breaks it down by whatever your requests tag themselves with

Tagging requests with metadata is what makes the last one useful.

When a call fails

Status	Read it as
`401`	The token is expired, malformed, or is actually a gateway API key
`403`	The token is valid but scoped to a different tenant, or the service account’s role does not cover this operation
`404`	A slug was passed where an ID was expected, or the resource belongs to a workspace you did not name
`409`	The resource already exists. Most creates are not idempotent

Every code the Admin API returns is listed on the Errors page.

Audit

Every administrative call is recorded with the principal that made it, the action, the target resource, a timestamp, an IP address and the request details. Automation is attributable to the service account that ran it, which is a good reason to give each one a name that says what it is for.

Authentication

Service accounts, access tokens, and how scope works across a TSG hierarchy

Errors

Every error code, with the usual cause

Audit Logs

The trail of every administrative change

Organisation Management

The same settings, configured from Strata Cloud Manager

API Reference

Gateway Configuration

Providers and Credentials

MCP

Administration

Observability

Your first request

Base URLs

How resources are scoped

Find a workspace’s ID

Slugs and IDs

Guardrails sit at both levels

Common tasks

When a call fails

Audit

Next

Authentication

Errors

Audit Logs

Organisation Management

​Your first request

​Base URLs

​How resources are scoped

​Find a workspace’s ID

​Slugs and IDs

​Guardrails sit at both levels

​Common tasks

​When a call fails

​Audit

​Next

Authentication

Errors

Audit Logs

Organisation Management

Your first request

Base URLs

How resources are scoped

Find a workspace’s ID

Slugs and IDs

Guardrails sit at both levels

Common tasks

When a call fails

Audit

Next