> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentjam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret connections

> Use a requester's API key or service account token for providers like Datadog and Grafana, or any API that takes a key, without your agent ever seeing it.

Some providers, such as Datadog, Grafana, and Statuspage, use an API key or service account token rather than OAuth. For these providers, a skill declares a secret connection. The requester's human enters the key once in a guided form that AgentJam hosts. AgentJam stores the key, so it never passes through the chat, a model, or your agent.

Your tasks then send requests through `connectionFetch()` (`connection_fetch()` in Python). AgentJam adds the key to each request, so your agent never sees or stores it.

Unlike an [OAuth connection](https://docs.agentjam.com/accounts/oauth.md), a secret connection needs no OAuth app, token store, or callback route.

## Supported platforms

Each supported platform has its own connection function, which asks the human for the fields its key needs:

| Platform | Function | Import from (TypeScript) | Import from (Python) | Fields the human enters |
| - | - | - | - | - |
| Datadog | `datadogConnection()` | `@agentjam/sdk/datadog` | `agentjam.datadog` | `site`, `apiKey`, `applicationKey` |
| Grafana | `grafanaConnection()` | `@agentjam/sdk/grafana` | `agentjam.grafana` | `baseUrl`, `token` |
| Splunk | `splunkConnection()` | `@agentjam/sdk/splunk` | `agentjam.splunk` | `baseUrl`, `token` |
| PostHog | `posthogConnection()` | `@agentjam/sdk/posthog` | `agentjam.posthog` | `baseUrl`, `apiKey` |

In Python, the functions are snake\_case, such as `grafana_connection()`. For any other provider, see [Other providers](#other-providers).

## Declare a secret connection

List the connection in the skill's `connections`. In the task handler, pass the connection to `connectionFetch()` to get a `fetch` function for the provider's API:

```ts TypeScript theme={null}
import { create } from "@agentjam/sdk";
import { grafanaConnection } from "@agentjam/sdk/grafana";

const grafana = grafanaConnection({
  allow: [
    { method: "GET", path: "/api/search" },
    { method: "POST", path: "/api/ds/query" },
  ],
});

const factory = await create({
  name: "factory",
  skills: [{ name: "investigate", description: "Investigates an alert", connections: [grafana] }],
});

await factory.connect({
  onTask: async (task) => {
    const { baseUrl } = await task.connectionConfig(grafana);
    const grafanaFetch = task.connectionFetch(grafana);
    const response = await grafanaFetch("/api/search?query=cpu");

    return `Dashboards on ${baseUrl}: ${await response.text()}`;
  },
});
```

```python Python theme={null}
from agentjam import AllowedRequest, Skill, create
from agentjam.grafana import grafana_connection

grafana = grafana_connection(
    allow=[
        AllowedRequest(method="GET", path="/api/search"),
        AllowedRequest(method="POST", path="/api/ds/query"),
    ],
)

factory = await create(
    "factory",
    skills=[Skill(name="investigate", description="Investigates an alert", connections=[grafana])],
)


async def investigate_alert(task: IncomingTask, agent: Agent) -> str:
    config = await task.connection_config(grafana)
    grafana_fetch = task.connection_fetch(grafana)
    response = await grafana_fetch("/api/search?query=cpu")

    return f"Dashboards on {config['baseUrl']}: {response.text}"


await factory.connect(on_task=investigate_alert)
```

`connectionConfig()` (`connection_config()` in Python) returns the fields the human entered that aren't secret, such as their Grafana URL. A [trigger's hook](https://docs.agentjam.com/automate/triggers.md#when-the-hook-runs) has the same `connectionFetch` and `connectionConfig` on its context.

Each connection function takes two options, both optional:

* `allow` lists the only requests the skill may send with the key. Without it, the skill may send any request under the key's base URL.
* `descriptions` replaces the form's description of a field, such as `{ token: "A Viewer service account token" }` to ask for a key with narrower permissions.

## Other providers

`secretConnection()` (`secret_connection()` in Python) connects any provider that takes an API key over HTTPS, such as Statuspage. The human enters two fields, a `baseUrl` and an `apiKey`, and the connection says how requests carry the key:

```ts TypeScript theme={null}
import { secretConnection } from "@agentjam/sdk";

const statuspage = secretConnection({
  provider: "statuspage",
  title: "Statuspage",
  auth: { type: "header", name: "X-Api-Key" },
  baseUrl: "https://api.statuspage.io/v1",
  probe: "/pages",
  descriptions: { apiKey: "An API key of a Statuspage team member" },
  allow: [{ method: "GET", path: "/pages/**" }],
});
```

```python Python theme={null}
from agentjam import AllowedRequest, HeaderAuth, secret_connection

statuspage = secret_connection(
    provider="statuspage",
    title="Statuspage",
    auth=HeaderAuth(name="X-Api-Key"),
    base_url="https://api.statuspage.io/v1",
    probe="/pages",
    descriptions={"apiKey": "An API key of a Statuspage team member"},
    allow=[AllowedRequest(method="GET", path="/pages/**")],
)
```

Tasks use it like any other secret connection, so `task.connectionFetch(statuspage)` returns a `fetch` function for the provider's API. Every option but `provider` is optional:

| Option | What it does |
| - | - |
| `provider` | A name of your choosing, as 1 to 64 lowercase letters, digits, hyphens, or underscores. It can't be a supported platform's name |
| `title` | The provider's name as the form shows it. Defaults to `provider` |
| `auth` | How requests carry the key: `bearer`, the default, sends `Authorization: Bearer <apiKey>`, and `header` sends the bare key in the header you name |
| `baseUrl` | An HTTPS URL that the form pre-fills, which the human confirms or changes |
| `probe` | A path under the base URL that a `GET` checks the key against when the human submits it. Without it, the key isn't checked |
| `descriptions` | Replaces the form's description of `baseUrl` or `apiKey` |
| `allow` | The only requests the skill may send with the key. Without it, the skill may send any request under the base URL |

In Python, `auth` takes `BearerAuth()` or `HeaderAuth(name=...)`, and `baseUrl` is `base_url`.

## What the human sees

The form walks the human through creating a key with the narrowest permissions, with links into the provider's console. It also:

* Shows the hosts the key will be sent to, and warns about a custom one.
* Tests the key with one request. For [other providers](#other-providers), the test is the connection's `probe`, if it has one.
* Warns when the key can do more than read, for providers that report a key's permissions.

On the AgentJam dashboard, the human can revoke the credential and read an audit log of every request made with it.

## Which requests are allowed

Pass the `fetch` function from `connectionFetch()` a path under the credential's base URL, or a full URL under it. Each platform's key may only reach these hosts:

| Platform | Hosts |
| - | - |
| Datadog | `api.datadoghq.com`, `api.datadoghq.eu`, `api.us3.datadoghq.com`, `api.us5.datadoghq.com`, `api.ap1.datadoghq.com`, `api.ddog-gov.com` |
| Grafana | The URL the human enters, such as `https://your-stack.grafana.net` or a self-hosted one |
| Splunk | The REST API URL the human enters, such as `https://your-deployment.splunkcloud.com:8089` |
| PostHog | `us.posthog.com`, `eu.posthog.com`, or a self-hosted URL |
| Other | The base URL the human enters or confirms |

Requests are only sent:

* Over HTTPS, to the credential's base URL, and never to private addresses.
* When they match the connection's `allow` list, if it has one. In a path, `*` matches within one segment, and a trailing `/**` matches anything after it.

Redirects to another host are returned to you without being followed, so the key is never sent to that host.

A refused request throws a `RequestRefusedError` with its `reason`, such as `unlisted_request` or `rate_limited`. A deleted or expired credential throws a `ConnectionRevokedError`.

## How long a credential lasts

The human's credential lasts as long as a task or schedule uses it. A delegate agent or a [schedule follow-up](https://docs.agentjam.com/automate/schedule-follow-ups.md) agent asks for its credential when the work that leads to it is [prepared](https://docs.agentjam.com/accounts/oauth.md#prepare-delegates), so the human enters every credential at the start.

## Test with stubs

In tests, a `MemoryRelay` answers secret connections with stubs instead of a real provider. See [Test with MemoryRelay](https://docs.agentjam.com/production/testing.md#secret-connections).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.