Home / Core concepts

Credential broker

The agent never holds the secret. Veefore seals material on the way in and leases short-lived, scoped credentials on the way out.

An agent that holds an API key is an agent whose API key is in its prompt context, in its logs, and in whatever the model decides to say next. Prompt injection becomes credential theft, and the blast radius is whatever that key can do.

The credential broker removes the key from the agent entirely. The agent asks Veefore to perform an action. Veefore decides. Only after the action is permitted does the broker issue a short-lived, scoped credential — to the tool runtime, not to the agent.

#The flow

1. You register a credential reference with its material. Veefore seals the material with VEEFORE_DATA_ENCRYPTION_KEY.
2. You attach the credential to a tool.
3. An agent requests an action on that tool.
4. The pipeline runs. Stage 10 is the first stage with an external side effect — every refusal has already happened.
5. The broker issues a lease: a short-lived credential, scoped to this action.
6. The tool runtime uses it. The lease is recorded by reference and expires.

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

#Registering one

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": "…",
      "header": "x-api-key"
    }
  }'

Supported types: API_KEY, BEARER_TOKEN, BASIC_AUTH, DATABASE_DSN, OAUTH_CLIENT, MTLS_CERTIFICATE, SIGNING_KEY.

#Secrets never come back out

No endpoint returns credential material. GET /v1/credentials returns metadata only: key, name, type, provider, status, created, last rotated, lease count.

The guarantee is enforced in several places at once, deliberately:

• The repository layer does not select the sealed column into API responses.
• Log redaction strips credential-shaped values from every log line.
• Audit events record the credential by id, never by value.
• npm run quality:audit fails the build on a committed secret.
• The CLI smoke test asserts no command prints a secret.

If you lose the material, you rotate. You do not read it back. That is the intended one-way door.

#Rotation

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": "…", "header": "x-api-key" } }'

Rotation seals the new material and invalidates every outstanding lease. An in-flight action holding an old lease fails rather than continuing with a credential you have decided to retire.

credential:rotate requires step-up authentication. The status moves through ROTATING while it happens, so the transition is observable.

Rotate on a schedule. veefore doctor reports credentials that are overdue, and CREDENTIAL_ANOMALY is a risk signal that fires on unusual credential use.

#Revocation

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" }'

Immediate. Every lease dies, and every tool depending on the credential starts failing at stage 10 with INVALID_CREDENTIAL_REFERENCE. credential:revoke is high impact and step-up gated.

#Providers

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

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

#Why stage 10 and not earlier

Brokering is the first irreversible step. Everything before it — authentication, identity, lifecycle, capability, delegation, policy, risk, approval — can refuse with no trace outside Veefore.

Putting the broker after all of them is what makes BLOCK mean blocked. Brokering earlier, say for performance, would mean a blocked action had already caused a credential to be issued. Then "we blocked it" and "the secret did not go out" would be two different claims, and only one of them would be true.

#Related