Skip to main content
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, 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: In Python, the functions are snake_case, such as grafana_connection(). For any other provider, see 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:
connectionConfig() (connection_config() in Python) returns the fields the human entered that aren’t secret, such as their Grafana URL. A trigger’s hook 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:
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: 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, 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: 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 agent asks for its credential when the work that leads to it is prepared, 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.