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’sconnections. 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:
allowlists the only requests the skill may send with the key. Without it, the skill may send any request under the key’s base URL.descriptionsreplaces 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:
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.
Which requests are allowed
Pass thefetch 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
allowlist, if it has one. In a path,*matches within one segment, and a trailing/**matches anything after it.
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, aMemoryRelay answers secret connections with stubs instead of a real provider. See Test with MemoryRelay.