Authentication

Admin API requests are authorised with a short-lived access token issued by Strata Cloud Manager, not with an AI Gateway API key.

A gateway API key, the key you send as Authorization: Bearer $API_KEY on inference requests, is not accepted on any Admin API endpoint. See Inference API authentication for the inference path.

You obtain an Admin API token by authenticating a service account against the Palo Alto Networks authentication service. The token carries the ID of the tenant service group (TSG) it was scoped to, and every request made with it is routed to that tenant.

What you need

Before you can request a token, three values must exist. All three come from Strata Cloud Manager.

Value	What it identifies	Where it comes from
TSG ID	The tenant the token will act on. One TSG corresponds to one AI Gateway organisation.	Shown against the tenant in Strata Cloud Manager
Client ID	The service account	Issued when the service account is created
Client Secret	The service account’s credential	Shown once, at creation

A TSG must have a service account before you can make any API call against it. If a tenant has no service account of its own, a service account belonging to one of its ancestor TSGs can be used instead. See Token scope within a TSG hierarchy.One TSG may have many service accounts, and one service account may have many tokens.

Tenant service group and tenant are used interchangeably; there is no functional difference between them.

Create a service account

Service accounts are created in Strata Cloud Manager, through Common Services Identity & Access. A service account is not tied to a specific user.

Open Identity & Access

Select the tenant

Choose the tenant the service account belongs to.A service account added to a parent tenant is automatically added to all of that tenant’s children, which is how a parent manages its children. Add it to a child tenant instead if you do not want that inheritance.Creating service accounts in different tenant service groups lets you assign different roles for different access permissions, and keeps the audit trail readable.

Add the identity

Select Add (or Add Identity), then set Identity Type to Service Account.Give it a unique and meaningful Service Account Name. Optionally add a Service Account Contact email and a Description. The contact person is not added as a user.

Save the client credentials

Select Next. The Client Credentials screen shows the Client ID and Client Secret.

The Client Secret is presented once. Copy both values, or select Download CSV File, before leaving the screen. If you lose the secret you must issue a new credential.

Note the TSG ID

Select Next. The display name of the service account is formatted as <ServiceAccountName>@<tsg_id>.iam.panserviceaccount.com.Every service account of a parent tenant carries the parent TSG ID, and every service account of a child tenant carries the child TSG ID. Take note of the tsg_id, because you pass it on every token request.

Assign a role

On the Assign Roles screen, select the scope (for example All Apps & Services) and assign the role the service account needs. A service account with no role assignment cannot obtain a token.Grant the narrowest role that covers the Admin API operations you intend to automate. A custom role needs iam.service_account and iam.custom_role permissions if the account will manage identities itself.

Submit

Save to create the service account. You now have the Client ID, Client Secret and TSG ID needed to request a token.

Request an access token

Exchange the service account credentials for an access token with POST /oauth2/access_token.

The authentication service runs on a different FQDN from the rest of Strata Cloud Manager: https://auth.apps.paloaltonetworks.com

The endpoint uses basic auth, with the Client ID as the username and the Client Secret as the password, and takes the TSG ID in the scope field:

Request an access 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

The service account you authenticate with must belong to the TSG named on scope, or to one of its ancestors. A successful response carries the token and its lifetime in seconds:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900
}

Access tokens have a lifespan of 15 minutes. Read expires_in rather than hard-coding the number, cache the token in memory for the life of that window, and refresh it about a minute before it lapses. Requesting a fresh token per API call is unnecessary; carrying one across a long-running job is what fails.

Call an Admin API endpoint

Send the token as a bearer token. Every Admin API endpoint takes the same header; the base URL and path for each one are shown on its own reference page.

curl https://api.apps.paloaltonetworks.com/ai_gw/v2/configs \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"

You do not pass the TSG ID on the request. The token already contains it, and the request is routed to that tenant on the strength of it.

Token scope within a TSG hierarchy

A token issued for one TSG cannot be used against another. If you have a tenant, Tenant 1A, with a service account named 1a_svc, then a token obtained through 1a_svc reaches Tenant 1A and nothing else. When you run multiple tenants you organise them as a hierarchy of TSGs. Creating a dedicated service account for every TSG and tenant in that hierarchy is the simplest arrangement, but it is not necessary. A service account belonging to a TSG can name any descendant of that TSG when it requests a token. Consider a root TSG A with two tenants, and a child TSG B with two more: Assume a_svc and b_svc were created with the superuser role on TSG A and TSG B respectively. Then:

a_svc can request a token for any TSG ID in the hierarchy, because every TSG and tenant shown is a descendant of TSG A.
b_svc can request tokens for TSG B, Tenant 1B and Tenant 2B, its own descendants.
b_svc cannot request a token for TSG A, Tenant 1A or Tenant 2A. Those are its ancestor and its peers.
Tenants 1A, 2A, 1B and 2B hold no service accounts of their own, so only the service accounts of their parent TSGs can obtain tokens for them.

The TSG IDs used in the examples on this page are deliberately fake. Real TSG IDs are 10-digit integers, such as 1000000001.

Grant cross-hierarchy access with an access policy

b_svc cannot obtain a token for Tenant 1A, because Tenant 1A sits outside its subtree. Where you need exactly that, create an access policy on Tenant 1A naming the Client ID of b_svc as the principal. The policy overrides the hierarchy restriction for that one pairing. You can do this from the multitenant UI, or with the Identity and Access Management create an access policy API. The following grants b_svc superuser permissions on Tenant 1A, represented here by TSG ID 18:

Grant b_svc access to Tenant 1A

curl -d '{"role":"superuser","resource":"prn:18::::","principal":"b_svc@15.iam.panserviceaccount.com"}' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST https://api.strata.paloaltonetworks.com/iam/v1/access_policies

The token you authenticate this call with must itself be scoped to the TSG that owns the resource, 15 in the example above. The same endpoint grants a person a role on a tenant, with their email address as the principal. Three fields make up a policy:

Field	Format
`principal`	A user’s email address, or a service account as `<name>@<tsg_id>.iam.panserviceaccount.com`
`resource`	`prn:<tsg_id>::::<workspace>`. Leave the last segment empty for the TSG root, which Strata Cloud Manager labels All Apps & Services
`role`	A built-in role is a bare slug, such as `superuser` or `view_only_admin`. A role defined by a tenant carries that tenant’s ID, as `my_custom_role:1000000001`

GET /iam/v1/access_policies lists the policies on the tenant your token is scoped to, and DELETE /iam/v1/access_policies/{id} removes one. A duplicate POST returns 409, so the call is safe to retry.

The access policy endpoint does not check that the principal exists. A POST naming an address that belongs to nobody returns 201 and a policy ID, and the policy sits in the listing doing nothing until somebody with that address appears. Validate addresses against your directory before creating policies in bulk, and review the IDs you get back.

Older Palo Alto Networks documentation shows this endpoint as https://api.sase.paloaltonetworks.com/access_policies. https://api.strata.paloaltonetworks.com/iam/v1/access_policies is the current host and path.

Check your token

If the credentials baked into a token are not the ones you expect, the Admin API rejects the request and the error reports an invalid authorisation code. Paste the token into jwt.io to decode it and read the claims back. The decoded payload shows the tsg_id the token was issued for, which is the fastest way to confirm you are hitting the tenant you think you are, and an access claim listing the roles the service account holds on it.

Common failures

Symptom	Cause
Token request rejected at `/oauth2/access_token`	The Client ID or Client Secret is wrong, or the service account has no role assignment
Token request rejected for the TSG on `scope`	The service account is not in that TSG or an ancestor of it. Create an access policy
Admin API returns an authorisation error with a valid-looking token	The token has expired, since they last 15 minutes, or it is scoped to a different tenant. Decode it and check `tsg_id`
Admin API rejects a key that works for inference	A gateway API key was sent instead of an access token. Only tokens from the authentication service are accepted

Admin API introduction

What the Admin API manages, and the permissions model behind it

Inference API authentication

Gateway API keys and JWT authentication for inference requests

Errors

Admin API error codes and what they mean

Audit logs

Every administrative action, attributed to the principal that made it

API Reference

Gateway Configuration

Providers and Credentials

MCP

Administration

Observability

What you need

Create a service account

Request an access token

Call an Admin API endpoint

Token scope within a TSG hierarchy

Grant cross-hierarchy access with an access policy

Check your token

Common failures

Admin API introduction

Inference API authentication

Errors

Audit logs

​What you need

​Create a service account

​Request an access token

​Call an Admin API endpoint

​Token scope within a TSG hierarchy

​Grant cross-hierarchy access with an access policy

​Check your token

​Common failures

​Related

Admin API introduction

Inference API authentication

Errors

Audit logs

What you need

Create a service account

Request an access token

Call an Admin API endpoint

Token scope within a TSG hierarchy

Grant cross-hierarchy access with an access policy

Check your token

Common failures

Related