---
title: "Connections and hooks"
description: "Look up the fields for connections and hooks."
canonical_url: "https://docs.oz0.ai/reference/plugin-manifest/connections"
---
# Connections and hooks

> Look up the fields for connections and hooks.

For: Plugin authors looking up manifest fields.

Look up the fields for connections and hooks.

## `connections[]`

How the plugin's tools reach other systems as the tenant. See [Connections in a plugin](https://docs.oz0.ai/build/parts/connections).

<field-group>
<field name="name" type="string" :required="true">

The connection's name in the tenant, in its callback's URL: lowercase letters, digits and dashes, starting with a letter, at most 31. The tenant secrets its steps save start with it in capitals.

</field>

<field name="tools" type="string[]" :required="true">

This plugin's tools whose calls may get its token.

</field>

<field name="params" type="map[]">

What an admin gives when connecting: `name`, `description`, `default`, `required`, and `choices`, the values it may take when it is one of a few (the web UI shows a select). A `default` may name the tenant, such as `"{tenant}-oz0"`. `max_length` is the most characters the param may have, such as an app name the other system limits: a longer value given is refused, and a `{tenant}` default is shortened to fit.

</field>

<field name="steps" type="map[]">

The steps the admin's browser goes through: `name`, `description`, `browser`, `pkce`, `callback`, `exchange`, `save`, and `when`, the params and values the step runs with (`{account: user}`); a flow skips a step whose params differ, and needs the params the steps it runs read.

A **guided step** has no `browser` and runs on the edge's own page instead: `create` (a link that makes the app on the other system, `json_query` for a URL-encoded JSON document), `copy` (values to copy into its settings), `paste` (fields the admin pastes back, each a `secret` or a `value` with a `format`) and `verify` (checks that must pass: a `request` with `expect`, or a signed `delivery` to one of the plugin's event sources).

A pasted field may be both a `secret` and a `value`.

A guided step may offer a `package`: `label`, `file` (a `.zip` name), `manifest` (a JSON template) and `icons` (`color`, `outline`), which the edge builds. See [guided steps](https://docs.oz0.ai/build/parts/connections/setup-and-security#guided-steps).

</field>

<field name="token" type="map" :required="true">

What a call gets: `kind` (`secret`, `jwt-exchange`, `client-credentials`, `identity`, `on_behalf_of` or `federated`), `secret`, `fallback_secret`, `jwt`, the token request (`method`, `url`, `headers`, `scope_field`, `resource_field`, `token_field`, `expires_field`), for `client-credentials` `client_id`, `client_secret` (a tenant secret's name, which stays on the edge) and `scope`, with `client_auth: private_key_jwt` and `client_key_id` to sign a client assertion with a private key instead of sending a secret ([private key](https://docs.oz0.ai/build/parts/connections#a-private-key-instead-of-a-client-secret)), and `pass`.

A `client-credentials` `url` names its host literally, or `https://{params.<name>}/` when a guided step pastes the client secret (sent only to the origin it was pasted for).

`refresh` renews a `secret` token a step saved: `url`, `secret` (the refresh token's tenant secret, saved by a step, which reaches no node), `client_id`, `client_secret` (a confidential client's; none for a public client; with a `url` on `https://{params.<name>}/`, a guided step pastes it, and it goes only to the host it was pasted for), `scope` and `resource` ([refresh tokens](https://docs.oz0.ai/build/parts/connections/token-lifecycle#refresh-tokens)).

`secret` and `fallback_secret` are named with the connection's prefix and are never `jwt.key`; no step saves the `fallback_secret`; and `requires.secrets` may not name `jwt.key`, which reaches no node.

For `identity`, use `profile` and `audience`; `on_behalf_of` exchanges a delegated token at `url`, with optional `scope` and client credentials. See [Identity tokens](https://docs.oz0.ai/build/parts/connections/token-lifecycle#identity-tokens).

The `federated` kind uses the `federated` block for a cloud's short-lived credential and requires a credential-injection binding; see [Clouds](https://docs.oz0.ai/build/parts/connections/token-lifecycle#clouds).

</field>

<field name="scopes" type="map[]" :required="true">

Which functions get a token: `functions` (`<tool>.*` for every function of a remote tool on the connection), and the `scope` and `resource` of each one's token.

</field>

<field name="after" type="map[]">

Functions of the connection's tools that run once each time its last step is done, each as a tool job of its own: `call` (`<tool>.<function>`) and `arguments`, each a template of `{params.*}` and `{values.*}`. At most four ([after connecting](https://docs.oz0.ai/admin/connections#after-connecting)).

</field>
</field-group>

## `hooks[]`

See [Hooks](https://docs.oz0.ai/build/parts/hooks).

<field-group>
<field name="on" type="string" :required="true">

`pre_tool_call`, `post_tool_call`, `job_start` or `job_end`. `pre_llm_call` is accepted and does not run yet.

</field>

<field name="call" type="string" :required="true">

The function that answers, `<tool>.<function>`, of one of this plugin's tools (or its address with this plugin's own name).

</field>

<field name="match.tools" type="string[]">

For tool events: the `<tool>.<function>` names the hook applies to, or their addresses (`github/oz0_github.*`); `*` matches any function. Empty means every call. Each is at most 256 bytes ([Addresses](https://docs.oz0.ai/reference/plugin-manifest/dependencies#addresses)).

</field>

<field name="match.agents" type="string[]">

Only these agents' calls and jobs, by name or address (`github/oz0-github`). Empty means every agent of the tenant.

</field>

<field name="timeout" type="duration">

How long the hook may take, such as `2s`. The default is 2 seconds, the most 30.

</field>

<field name="on_timeout" type="string">

What a hook that does not answer in time, fails, or gives no decision counts as: `allow`, `deny` (the default) or `escalate`.

</field>

<field name="decisions" type="string[]">

`[allow, escalate]` for a hook that may only let a call through or send it to a person: any other answer, a failure and a timeout count as `escalate`, its `on_timeout` must be `escalate` or left out, and its `pre_tool_call` event carries the job's request. No other list is accepted ([Hooks that may only escalate](https://docs.oz0.ai/build/parts/hooks#hooks-that-may-only-escalate)).

</field>

<field name="scan" type="string[]">

`[secrets]` on a `post_tool_call` or `job_end` hook: the node tells the hook where the tenant's own secrets are in the result or the output, by path, position and name, never by value. `plugin inspect` lists it among the permissions, and a hook answered by a remote (`url`) tool may not ask for it ([Known secrets in a result](https://docs.oz0.ai/build/parts/hooks#known-secrets-in-a-result-scan)).

</field>
</field-group>

[Back to oz0-plugin.yaml](https://docs.oz0.ai/reference/plugin-manifest).


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.