Agent Access Tokens

An agent access token lets a client application use an agent without signing in with Microsoft Entra ID. This is useful for public applications, such as a chat widget on a website, that call the Core API on behalf of anonymous users.

Overview

Each agent access token is bound to a single agent. When a client sends a valid token in the X-AGENT-ACCESS-TOKEN header, the Core API runs the request as a virtual user that represents the token:

Virtual user property	Value
User identifier	The token ID (a GUID).
User principal name	`aat_{agentName}_{tokenId}@foundationallm.internal_`
Group memberships	The agent's virtual security group and the platform-wide all-agents virtual security group.

Access for token holders is granted through role assignments on the agent's virtual security group. The platform generates the virtual security group ID when the agent is first saved and, at the same time, assigns it the Reader role on the agent. That role assignment is what allows token holders to create sessions and request completions.

A token is rejected when it has expired, when it is inactive, when it was issued for a different agent, or when its secret does not match.

Prerequisites

The agent must already be saved. The virtual security group ID and the Agent access tokens section appear on the Security tab only after the agent has one.
To create tokens, you need write access to the agent and a role assignment for the Agent Access Tokens Contributor role.

Create an Agent Access Token

In the sidebar, select Agents > Agents.
Find the agent and select the edit (pencil) icon.
Open the Security tab.
In the Agent access tokens section, select the + (Create Access Token) button.

In the Create Access Token dialog, fill in the fields:

Field	Description
Token description	Required. A description that identifies the token, for example the application that will use it.
Token expiration date	Required. The date after which the token is no longer valid. Defaults to 90 days from today.

Select Create access token.
The dialog changes to View Access Token Details and shows the token value. Store it now: the value is never shown again.
- Select the copy icon to copy the token to the clipboard.
- Select Save to download the token as a text file.
- Select Close when you are done.

The Agent access tokens table lists the agent's tokens with their Description and Expiration Date. Token values are not shown.

Delete an Agent Access Token

On the agent's Security tab, find the token in the Agent access tokens table.
In the Delete column, select the trash icon.
In the Delete Access Token dialog, select Delete access token.

Requests that use a deleted token fail authentication.

Grant Access to the Virtual Security Group

The Reader role assignment for the agent's virtual security group is created automatically when the agent is first saved. If that role assignment has been removed, or you want token holders to have a different role, add a role assignment for the virtual security group:

On the agent's Security tab, select the copy icon next to Virtual security group ID.
Select Access Control.
In the Access Control dialog, open the Agent tab and select Add role assignment for this Agent.
Confirm that the scope is providers/FoundationaLLM.Agent/agents/{agentName}.
For Principal Type, select Group.
In Principal ID, paste the virtual security group ID.
Under What role to assign?, select Reader (or the role you need).
Select Create role assignment.

Use an Agent Access Token with the Core API

Send the token in the X-AGENT-ACCESS-TOKEN header. No Entra ID bearer token is required. {coreApiUrl} is the Core API base URL, and {instanceId} is your FoundationaLLM instance ID.

Create a Conversation

POST {coreApiUrl}/instances/{instanceId}/sessions
X-AGENT-ACCESS-TOKEN: {token}
Content-Type: application/json

{
  "name": "Website chat",
  "agent_name": "{agentName}"
}

Save the sessionId value from the response. It is needed for completion requests.

Request a Completion

POST {coreApiUrl}/instances/{instanceId}/completions
X-AGENT-ACCESS-TOKEN: {token}
Content-Type: application/json

{
  "agent_name": "{agentName}",
  "session_id": "{sessionId}",
  "user_prompt": "Why is the sky blue?"
}

For long-running requests, start the completion with POST {coreApiUrl}/instances/{instanceId}/async-completions and poll GET {coreApiUrl}/instances/{instanceId}/async-completions/{operationId}/status.

The Core API accepts agent access tokens on its sessions, completions, async completion status, files, code sessions, memory, users, and realtime speech endpoints.

Manage Tokens with the Management API

Agent access tokens are child resources of the agent (agentAccessTokens resource type):

GET    {baseUrl}/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/{agentName}/agentAccessTokens?api-version=2024-02-16
POST   {baseUrl}/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/{agentName}/agentAccessTokens/{tokenId}?api-version=2024-02-16
DELETE {baseUrl}/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/{agentName}/agentAccessTokens/{tokenId}?api-version=2024-02-16

{tokenId} is a new GUID for the token. The POST body contains id (the same GUID), name, description, expiration_date, and active. The response resource value is the token, and it is returned only once.

Quotas for Token Holders

Rate limit and usage limit quotas can apply to a single agent access token. Under Quotas > Quotas, select a specific agent in the quota context, then choose the agent access token in Applies to (optional). See Configuring Quotas.

Table of Contents