Reference

Authentication and authorization

Bearer tokens, API keys, service profiles, sessions, federation, MFA, MCP tokens, webhook signatures, grants, envelopes, and row/field policy.

Vadyl separates authentication, project scope, capability grants, governance envelopes, row policy, field masks, and execution-surface authority. A request is allowed only when every layer agrees.

Canonical headers

Header	Purpose
`Authorization`	Bearer user, service, API-key, or MCP access token.
`X-Vadyl-Tenant`	Tenant slug or canonical tenant ID.
`X-Vadyl-Project`	Project slug or canonical project ID.
`X-Vadyl-Branch`	Optional branch override for preview/sandbox reads and writes.
`Idempotency-Key`	Safe retry key for create, external egress, webhook replay, and agent/tool dispatch.
`If-Match`	Optimistic concurrency token or publication/branch precondition.

Authentication modes

Mode	Use for	Notes
Bearer session/user token	Dashboard, web apps, mobile apps, developer tools	Materializes `ActorContext`, roles, claims, auth strength, context sets.
API key + secret	CI, server-to-server jobs	Maps to a service profile and grant set; rotate without changing project code.
Service profile	Internal runtime, scheduled jobs, webhook handlers	Strictly bounded by publication, surface, and grant descriptors.
MCP token	External MCP clients	Bound to an MCP exposure; dispatched through the same operation dispatcher.
Webhook HMAC	Inbound/outbound webhook trust	Verified over raw bytes before parsing; management API still uses bearer auth.
Federation	OIDC, SAML, passkeys, MFA, JIT provisioning	IdentityEntrypoint and IdentityManagement own the control surface.

Request and response

identity-me.example

curl https://api.vadyl.app/v1/identity/me \
  -H "Authorization: Bearer $VADYL_TOKEN" \
  -H "X-Vadyl-Tenant: acme" \
  -H "X-Vadyl-Project: billing"

Authorization pipeline

Authenticate the caller and materialize ActorContext.
Resolve tenant/project/branch scope and project authority.
Merge governance envelopes through the project ancestry chain.
Check capability grants and operation-level required roles.
Evaluate row policy, field masks, branch policy, and publication pins.
Emit audit/observability evidence and expose explainability records.

Denied response

HTTP/1.1 403 Forbidden
{
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Actor cannot read Order rows in this project scope.",
    "reasonCode": "Access.DeniedByPolicy",
    "correlationId": "01HXZ0J4YV8AJF2GFG2T1F7Y42",
    "explainUrl": "/api/Explainability/access/read?correlationId=01HXZ0J4YV8AJF2GFG2T1F7Y42"
  }
}

MFA and step-up

POST /api/identity/challenge/start
{ "subjectId": "usr_123", "requireStrength": "mfa-webauthn", "reason": "publish.production" }

POST /api/identity/challenge/verify
{ "challengeId": "chl_123", "proof": { "kind": "webauthn", "assertion": "..." } }

Policy result meanings

Decision	Meaning
`Allow`	All auth, grant, row, field, branch, and envelope checks passed.
`Deny`	A required policy failed. Do not retry without changing authority or input.
`Mask`	Entity is visible but specific fields are removed or redacted.
`Challenge`	Operation needs stronger auth, MFA, approval, or elevated role.

Project capability surfaces

REST API