Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Credentials & Access

Access & Security

Issue the keys that let applications call the agent, and limit where its widget may run.

Access & Security controls how the agent is reached from outside the platform. It has three sections:

  • Access Keys: the API keys and widget keys that applications use to call the agent.

  • Allowed Domains: the web origins where the agent's embedded widget may run.

  • A2A: whether partner agents can discover and call this agent over the Agent2Agent (A2A) protocol.

The keys and domains set here are the same ones the Integrate Agent panel uses, so you can manage them from either place.

To open it, go to Agent Config and select Access & Security under Credentials & access.

The Access and Security page in Agent Config, with the Access Keys table showing one active widget key and the Allowed Domains list below it
Access & Security, with Access Keys above and Allowed Domains below.

Access Keys

The Access Keys table lists the agent's credentials.

Column
What it holds

Name

A friendly name for the key, for example Default, Production Widget or Mobile API.

Key

The credential value, displayed masked as ********. Select the copy icon beside it to copy the unmasked value.

Type

API Key or Widget Key. See Key types.

Status

Active, or deactivated (the row is dimmed). A deactivated key is no longer accepted.

Each row has a ⋯ menu with Rename and Deactivate.

Key types

The type of key you create depends on how the agent will be called.

  • Widget Key: used by the Embedded Chat widget and the TypeScript SDK client from Integrate Agent. It's safe to ship in browser code, because a widget key works only from the platform itself and the domains on the Allowed Domains list.

  • API Key: a key and secret pair for server-to-server calls to the Agent API. The key is sent as x-api-key, and the secret as x-api-key-secret.

A key works for its own agent only. An API key or widget key can run the agent it was created for. Used against any other agent, or against the Console or Governance Operator, the call is refused with 403. For a call over a socket, the same check applies when a chat starts and on each message.

Working with keys

Adding a key

The Add New Key dialog, with a Key Name field, a Key Type choice of API Key or Widget Key, and the Generate Key button
The Add New Key dialog.
  1. Select + Add Key.

  2. Enter a Key Name.

  3. Choose the Key Type: API Key or Widget Key.

  4. Select Generate Key.

The dialog then shows the new key, and for an API key, its API Secret. Copy both before you close the dialog: for security reasons, they can't be retrieved later.

Copying a key

Select the copy icon next to the masked key in the Key column. The platform places the unmasked value on your clipboard. The display stays masked.

Renaming or deactivating a key

The Access Keys table with a row's menu open, showing Rename and Deactivate
Each key's menu.

Open the ⋯ menu on the row:

  • Rename changes the key's name. The key value doesn't change.

  • Deactivate stops the key from being accepted. This can't be undone: a deactivated key can't be used again.

There's no rotate action. To replace a key, add a new one, move your integrations to it, then deactivate the old one.

Important Treat the unmasked key as a secret. Anywhere the key is pasted (application code, environment variables, configuration files) should follow the same handling rules as any other credential. Do not paste it into Instructions or commit it to a public repository.

Allowed Domains

Allowed Domains lists the web origins where the agent's embedded widget may run. A request made with a widget key is accepted only when the page it comes from is on this list, or is the platform's own domain. Anything else is refused. This is what stops your agent, and the data and quota behind it, from being embedded on a site you didn't authorize.

  • With the list empty, the widget runs nowhere outside the platform. Add every domain where you embed it.

  • The list applies to widget keys only. API-key calls are server-to-server and have no web origin, so they're checked by the key and secret alone.

Adding and removing domains

  1. Select + Add New Domain. A new row appears.

  2. Enter the URL or domain in the Enter URL field.

  3. To remove an entry, select the trash icon on its row.

  4. Select Save. Changes take effect only after you save.

The Whitelist domains step of the Embedded Chat setup on Integrate Agent adds to the same list.

For each environment where the widget is embedded, add its specific origin:

  • https://app.example.com: production app

  • https://staging.example.com: staging environment

  • http://localhost:3000: local development. Remove it before the agent goes to production.

A2A

Agent2Agent (A2A) is an open protocol that lets one agent find and call another across systems. Turning it on makes this agent reachable by partner agents. It is off by default.

Open the A2A tab and turn on Expose over A2A: Let other agents call this agent using the Agent2Agent (A2A) protocol. The switch takes effect as soon as you flip it. The tab lists two fields, each with a copy icon at its right end:

  • Agent Card URL: the discovery address partner agents read to learn what the agent can do. The tab notes Discovery endpoint for A2A clients. No authentication required. The card is public by design, because A2A clients need to read it before they can call the agent.

  • Authentication Header: how a partner calls the agent. It reads Required on every A2A call. Uses an API key and secret from Access Keys. The caller sends the key and secret together as Authorization: Bearer <apiKey>:<apiSecret>, so create a key for the partner under Access Keys and share it with them securely.

The A2A tab in Agent Config, Access & Security, with Expose over A2A turned off and the Agent Card URL and Authentication Header fields shown dimmed
The A2A tab, with Expose over A2A turned off.

The A2A tab is the third tab on Access & Security, after Access Keys and Allowed Domains. While Expose over A2A is off, as in the screenshot, the Agent Card URL and Authentication Header fields still show but are dimmed. Turn the switch on to use them.

Turning on A2A also creates an API key named A2A for the agent if it has no active key. Qore uses that key when it calls the agent as a sub-agent over A2A.

An agent called as a sub-agent with runWithA2A on the trigger request needs three things: A2A turned on, an active API key, and agent executor 1.4 or later. See Run sub-agents over A2A and choose the agent pool for the request fields and the errors it returns when one is missing.

A partner can send the agent a message, including files, then read, list, or cancel the tasks it started. A task is visible only to the key that started it. Streaming and push notifications aren't supported: those methods answer UnsupportedOperation, so a partner polls for the result. Both the A2A 1.0 and 0.3 message formats work, over JSON-RPC and over REST.

Files can arrive in two ways. A partner can send the file bytes inline, up to 5 MB, or send a public https link to the file, up to 300 MB. A link can't carry credentials. A private file has to be sent inline.

Security considerations

Three settings together govern how the agent is reached from outside:

  • Access Keys on this page: which credentials are valid.

  • Allowed Domains on this page: which web origins the widget may run on.

  • Authentication: which person is calling, verified against your identity provider.

What kinds of integration you expose is set up on Integrate Agent. A tight key list with a tight domain list produces an agent that's hard to call from anywhere you didn't intend. Loosening either one, by sharing one long-lived key everywhere or adding domains you don't need, widens the agent's exposure.

Why this matters

Keys are how an integration introduces itself to the agent at runtime. A leaked key (pasted into a public repo, exposed in a client-side bundle, or caught in a screenshot) is effectively the right to call the agent on your behalf. Name keys descriptively so you know which to replace when something goes wrong, and give each integration its own key. Sharing one key across all of them means deactivating it takes every integration down at once. Audit the domain list the way you'd audit a firewall rule: add origins deliberately and remove the ones you no longer need.

Last updated

Was this helpful?