> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/ai-workbench-qore/console/agent-builder/deploy/authentication.md).

# 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](https://docs.uptiq.ai/ai-workbench-qore/console/agent-builder/deploy/agent-integration.md) panel uses, so you can manage them from either place.

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

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-65405dddbef0788cdba754bc9c170147f9dba5a6%2Fqore_agent-builder_manage-agent-access-and-security_rounded_shadow.png?alt=media" alt="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"><figcaption><p>Access &#x26; Security, with Access Keys above and Allowed Domains below.</p></figcaption></figure>

### Access Keys <a href="#access-keys" id="access-keys"></a>

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](#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 <a href="#key-types" id="key-types"></a>

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](https://docs.uptiq.ai/ai-workbench-qore/console/agent-builder/deploy/agent-integration.md). 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](#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.

{% hint style="warning" %}
**The API secret is shown once, when the pair is generated.** The Access Keys table shows the key, never the secret. If you didn't record it, create a new API key and switch your integration to it. Keep both values server-side; the widget key is the only credential here that may ship in browser code.

One exception: **Download as MD** on the Agent API tab of Integrate Agent has an **Include secrets** option that writes the agent's API key and secret into the downloaded file. Treat that file as a credential.
{% endhint %}

### Working with keys <a href="#working-with-keys" id="working-with-keys"></a>

#### Adding a key <a href="#adding-a-key" id="adding-a-key"></a>

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-c0c452c197b1ba4ac5c997e3705c0e518caacaef%2Fqore_agent-builder_manage-agent-access-and-security-add-key_rounded_shadow.png?alt=media" alt="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"><figcaption><p>The Add New Key dialog.</p></figcaption></figure>

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 <a href="#copying-a-key" id="copying-a-key"></a>

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 <a href="#renaming-or-deactivating-a-key" id="renaming-or-deactivating-a-key"></a>

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-69ab1e50b75ddc378996cec6020e9089ddffe849%2Fqore_agent-builder_manage-agent-access-and-security-key-menu_rounded_shadow.png?alt=media" alt="The Access Keys table with a row&#x27;s menu open, showing Rename and Deactivate"><figcaption><p>Each key's menu.</p></figcaption></figure>

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 <a href="#allowed-domains" id="allowed-domains"></a>

**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 <a href="#adding-and-removing-domains" id="adding-and-removing-domains"></a>

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](https://docs.uptiq.ai/ai-workbench-qore/console/agent-builder/deploy/agent-integration.md#embedded-chat) adds to the same list.

{% hint style="warning" %}
Enter each domain exactly as the browser sends it, and test it against your intended origin before you rely on it in production. A mismatch in protocol, subdomain or port is refused like any other unlisted origin.
{% endhint %}

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 <a href="#a2a" id="a2a"></a>

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.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-464bb703e5929692a9251ceb6fca470831dd2b4c%2Fa2a-tab.png?alt=media" alt="The A2A tab in Agent Config, Access &#x26; Security, with Expose over A2A turned off and the Agent Card URL and Authentication Header fields shown dimmed"><figcaption><p>The A2A tab, with Expose over A2A turned off.</p></figcaption></figure>

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](https://docs.uptiq.ai/ai-workbench-qore/console/agent-builder/deploy/agent-integration.md#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.

{% hint style="warning" %}
**Exposing an agent over A2A makes it callable from outside your organization** by anyone who holds a key for it. Turn it on only for an agent you intend partners to call, and revoke the partner's key to cut access.
{% endhint %}

### Security considerations <a href="#security-considerations" id="security-considerations"></a>

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**](https://docs.uptiq.ai/ai-workbench-qore/console/agent-builder/deploy/authentication-1.md): which person is calling, verified against your identity provider.

What kinds of integration you expose is set up on [Integrate Agent](https://docs.uptiq.ai/ai-workbench-qore/console/agent-builder/deploy/agent-integration.md). 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 <a href="#why-this-matters" id="why-this-matters"></a>

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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.uptiq.ai/ai-workbench-qore/console/agent-builder/deploy/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
