Documentation / Credentials / Use credentials

Use a credential from an agent

Bind a Credential to a governed Resource and expose only Resource operations to agent code.

Agents normally use Credentials indirectly. A Resource declares a named Credential slot, its integration interprets the material, and the Agent invokes the Resource operation. This keeps secret bytes outside prompts and agent input.

Before you begin

  • Create or authorize the Credential.
  • Deploy a Resource whose integration declares the required Credential slot.
  • Decide whether the Resource and Credential are fixed or selected by tenant, customer, or principal.

Steps

  1. Bind the Credential to the Resource's named slot.
  2. Bind the Resource to the Agent under a meaningful local name such as github.
  3. Expose only the required Resource operations as Tools.
  4. Grant resource:invoke, credential:use, and—when scoped—binding:use through Policy.
  5. Invoke the Agent through an authenticated Channel or platform API.

The Agent invokes a Resource operation, not a Credential operation:

ts
import { agent } from "@constal/sdk";

export default agent({
  id: "github-assistant", version: "1.0.0", model: "model",
  async onMessage(message, ctx) {
    return ctx.invoke(ctx.resources.github!, "issue.list", {
      owner: "acme", repository: "support", state: "open",
    }, { timeoutMs: 30_000 });
  },
});

The github binding identifies a fixed or scoped service Resource. That Resource declares the Credential slot and integration behavior. During invocation, Constal resolves the active encrypted Credential version, authorizes its use, and supplies material only to the protected integration code. Ctx has no secret() method; Agent and Tool code cannot read reusable Credential values.

Conceptually, the relationship is:

text
Agent Tool → Resource operation → integration → named Credential slot → active encrypted version

Agent code receives a Resource handle, not secret material. Constal resolves and authorizes the Credential at the operation boundary.

Verify

After one successful invocation:

  • the Credential detail page should list the Resource under Where it is used;
  • Recent activity should show the injected version and outcome;
  • the run identity should pin the Resource, Credential resolution, binding revision, and Policy decisions.

Troubleshooting

  • CredentialBindingRequired: the Resource declared a required scoped slot but no assignment exists for the authenticated owner.
  • BindingUseDenied: Policy denied the selected assignment.
  • CredentialUnavailable: there is no usable active version.
  • BindingContractMismatch: a scoped Resource assignment does not match the authored contract.

Next steps

For one shared Agent serving multiple owners, continue with Scoped bindings. For lifecycle operations, read Credential lifecycle. For Resource invocation and Tool design, read Resources and Tools.