> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/talus-docs-v2.1.0/faq/05-authorization.md). # Authorization {% hint style="info" %} **Audience:** Nexus adopters and integrators. **Goal:** Answer who may call or change a protected Tool so you can keep Agent, capability, and vertex authority separate. {% endhint %} This page covers two trust boundaries: the on-chain grant that lets an execution act for an Agent at a specific vertex, and the signed-HTTP channel that authenticates Leader-to-Tool calls. Both answer who is allowed to do what. Whether returned evidence satisfies a verifier is covered on the [verification page](/talus-docs-v2.1.0/faq/06-verification.md). #### On-chain Tool authorization **How is a step authorized to act on an Agent's behalf?** Through a **Task-bound per-vertex authorization grant**. `AgentVertexAuthorization` ties together the skill ID, interface revision, DAG, vertex, and Task ID; the occurrence's worksheet/current-Execution context proves which execution is using that Task-bound grant. It is not a durable exact-Execution trigger. A custody-touching Tool still must enforce its own recipient, amount, capability, sender, and state policy; fixed Tool identity and a signed result do not create application asset authority by themselves. **How does a scheduled Task stay authorized across many runs?** A scheduled Task stores a durable skill-level authorization object for the exact Agent, skill, and interface revision resolved when the Task is created. Each firing copies those pinned grants into the Occurrence's Execution. Updating the Agent's skill later does not rewrite an existing Task's authorization; close and recreate the Task when work must adopt a new skill revision. **Does an open Task freeze the Agent skill registry?** No. The Task snapshots its selected skill revision, DAG binding, and policy inputs, but the registry can later deactivate the Agent or skill, advance its revision, or change its DAG or policies. The registry classifies the immutable snapshot as `Current`, `Inactive`, `Stale`, or `Missing`: a matching inactive contract aborts before Execution without durable Task rejection and can recover through reactivation, while a revision/DAG/policy mismatch is `Stale` and an absent Agent or skill record is `Missing`. `Stale` and `Missing` are permanent for that snapshot and the explicit rejection path can record `StaleSkillContract`; close an idle old Task and create a new one, because `Missing` cannot be repaired by reactivation. Never infer that an open Task follows a registry mutation. **Signed HTTP and Tool identity** **What exactly does signed HTTP v3 prove?** The Leader signs the Tool schema's ordered canonical input hash. The Tool verifies that signature against a local allowlist, reconstructs the canonical input commitment from the received body, and rejects a mismatch before invocation. For a successful canonical result, the Tool signs the response-domain message containing the Leader signature, deterministic invocation nonce, and the domain-separated SHA-256 of exact ordered response BCS. The signatures do not bind the HTTP method, path, query, raw JSON bytes, wall-clock `iat`/`exp` claims, response status, or arbitrary headers. HTTPS protects those unsigned headers and the plaintext body on every hop. Signed HTTP proves provenance and integrity of the canonical commitments; it does not hide inputs/outputs from the Leader or prove a correctly signed business answer is true. **Which headers carry v3 evidence?** Requests carry the signature version, Leader capability ID, Leader key ID, canonical input hash, Leader signature, and deterministic nonce. Responses carry only the signature version and Tool signature. There is no Tool `kid` response header: workflow starts from the registered Tool ID and resolves that Tool's active on-chain key binding. The nonce is derived from execution ID, walk index, runtime vertex name, and iteration. It is bound by the Tool signature and recomputed on-chain; v3 does not use a time-window claim for replay resistance. **How are signing keys registered and discovered?** `NetworkAuth` binds a Leader capability identity or stable Tool ID to a sequence of Ed25519 keys. Registration requires the matching on-chain capability plus proof of possession of the private key. Only the active, non-revoked key verifies. A Tool provider uses: ``` nexus tool auth keygen --out ./tool-key.json nexus tool auth register-key --tool-fqn --signing-key nexus tool auth list-keys --tool-fqn ``` `register-key` resolves `OwnerCap` from `--owner-cap` or the saved CLI Tool record. Its result includes the Tool ID, binding object ID, active Tool key ID, public key, and transaction digest. The key ID selects the active registry entry; the Toolkit config and Tool response do not carry a Tool KID field. **How does key rotation work?** Registering the next Tool key advances the active key ID immediately. Quiesce old producers, register the replacement, update the Toolkit private key, and retry late responses under the new key. `--skip-if-active` avoids another registration when the same public key is already active, subject to the command's documented concurrent-run race. The public contract exposes the active Leader key binding and rejects stale, revoked, or mismatched signatures. Details of how a service process starts or rotates its private key are outside the hosted developer documentation; consumers should inspect the public binding and report repeated mismatch evidence with its request or transaction id. **Can a Tool verify Leaders without an RPC read per request?** Yes. Export every registered Leader with an active key, or keep the file synchronized: ``` nexus tool auth export-allowed-leaders --all --out ./allowed-leaders.json nexus tool auth sync-allowed-leaders --out ./allowed-leaders.json --interval 30s ``` Use repeated `--leader ` instead of `--all` when the Tool should trust a bounded set. `sync-allowed-leaders --once` performs one atomic refresh and exits. A file-backed Toolkit resolver reloads the path during key lookup, so the sync process remains outside the request path. *** **Where do I go next?** * [Verification](/talus-docs-v2.1.0/faq/06-verification.md) — how `RegisteredKey` and `External` accept or reject evidence. * [Verify an off-chain Tool result](/talus-docs-v2.1.0/guides/tool-development/verify-offchain-tool-result.md) — configure the complete v3 path. * [Registries and Discovery](/talus-docs-v2.1.0/concepts/08-registries-and-discovery.md) — understand the public Leader identity and active-key binding. * [Authorization and fixed Tools](/talus-docs-v2.1.0/concepts/09-authorization-and-fixed-tools.md) — understand Agent grants and fixed identity. * [`network_auth`](/talus-docs-v2.1.0/reference/move/nexus_registry/network_auth.md) and [Network Authentication Actions](/talus-docs-v2.1.0/reference/sdk/actions-network-auth.md) — inspect the exact registry and SDK surfaces. * [Glossary](/talus-docs-v2.1.0/glossary/glossary.md) — review grant, active-key, and proof-of-possession terms. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.talus.network/talus-docs-v2.1.0/faq/05-authorization.md?ask=&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 `build a script that syncs our docs to a CMS` 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.