Build / Wire it up

Broker a credential

Take the secret out of the agent entirely — including the material-key mistake that fails two layers from its cause.

The highest-value change you can make. An agent that holds an API key has that key in its prompt context, its logs, and whatever the model says next. Move it into the broker and prompt injection stops being credential theft.

#Register the credential

bashCopy
curl -X POST https://veefore.example.com/v1/credentials \
  -H "Authorization: Bearer $VEEFORE_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "key": "payments-api-key",
    "name": "Payments service API key",
    "type": "API_KEY",
    "provider": "local",
    "material": {
      "api_key": "sk_live_…",
      "header": "x-api-key"
    }
  }'

The response is metadata. No endpoint ever returns the material.

#Get material right

BASIC_AUTH, MTLS_CERTIFICATE and SIGNING_KEY are exempt from the single-secret check because their material is legitimately multi-field.

header and prefix control how an API_KEY is presented downstream:

jsonCopy
{ "api_key": "sk_live_…", "header": "x-api-key" }
{ "api_key": "sk_live_…", "header": "authorization", "prefix": "Bearer " }

#Attach it to a tool

bashCopy
curl -X POST https://veefore.example.com/v1/tools \
  -H "Authorization: Bearer $VEEFORE_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "workspace_id": "wsp_01JAV…",
    "key": "refund_customer",
    "name": "Refund a customer order",
    "kind": "HTTP",
    "required_capability": "refund.create",
    "endpoint_url": "https://payments.internal.example.com/refunds",
    "destination_allowlist": ["payments.internal.example.com"],
    "credential_id": "cred_01JAV…"
  }'

That is the whole integration. The agent never references the credential, never receives it, and does not need to know it exists.

#What happens at request time

Stage 10 of the pipeline — after authentication, identity, lifecycle, capability, delegation, policy, risk and approval have all passed:

1. The broker unseals the material.
2. It issues a lease: a short-lived credential scoped to this action.
3. The tool runtime injects it into the outbound request.
4. The lease is recorded by reference and expires.

Default lease lifetime is CREDENTIAL_DEFAULT_TTL_SECONDS, 600 seconds. Lease statuses: ISSUED, USED, EXPIRED, REVOKED.

#Migrating an agent that already holds a key

bashCopy
curl -X POST https://veefore.example.com/v1/credentials/cred_01ABC/rotate \
  -H "Authorization: Bearer $VEEFORE_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "material": { "api_key": "sk_live_NEW…", "header": "x-api-key" } }'

#Rotation and revocation

Rotation invalidates every outstanding lease, so an in-flight action holding an old lease fails rather than continuing with a credential you decided to retire. Status moves through ROTATING while it happens.

bashCopy
curl -X POST https://veefore.example.com/v1/credentials/cred_01ABC/revoke \
  -H "Authorization: Bearer $VEEFORE_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "reason": "Key published in a support ticket" }'

Revocation is immediate. Every tool depending on the credential starts failing at stage 10 with INVALID_CREDENTIAL_REFERENCE.

Both credential:rotate and credential:revoke require step-up authentication, and credential:revoke is high impact.

#Diagnosing a downstream 401

Veefore allowed the action and your downstream rejected what it received. In order of likelihood:

1. Wrong material key for the type. api_key versus token versus key. Now caught at registration, but an older credential may predate the check — rotate it and the check runs.
2. Wrong header. Your downstream wants x-api-key, you configured authorization, or vice versa.
3. Missing prefix. authorization usually needs Bearer including the trailing space.
4. The key itself is wrong or revoked downstream.

veefore logs --limit 20 shows the stage results. A CREDENTIAL stage of PASS with an EXECUTION stage carrying http_401 means Veefore brokered something and your downstream did not accept it — which narrows it to the first three.

#Providers

CREDENTIAL_BROKER_PROVIDER selects the backend. local seals material in PostgreSQL with VEEFORE_DATA_ENCRYPTION_KEY, which is right for development and for deployments where the Veefore database is already your trust boundary.

For production, point it at your existing secret manager so material lives where the rest of your secrets live and inherits that system's rotation, auditing and access control. Broker behaviour is identical either way.

#Related