S3 Gateway Credentials And Scopes

Gateway credentials are inbound downstream S3 credentials issued by Vaulthalla. They are not upstream provider credentials and should not reuse AWS, Cloudflare R2, or other provider keys.

Credential Types

Credential	Used by	Purpose
Gateway credential	Downstream S3 clients -> Vaulthalla	Authenticate AWS CLI, rclone, MinIO mc, SDKs, and apps to S3 Gateway.
Upstream provider credential	Vaulthalla -> upstream provider	Let Vaulthalla access an upstream S3/R2 bucket for an S3/R2 vault. Created with `vh api-key`.

The gateway secret access key is shown only when created. It is encrypted at rest and later used by Vaulthalla for SigV4 verification.

Scope Modes

Gateway credentials authenticate as an effective Vaulthalla principal user. The principal user's normal RBAC is always the ceiling. For role-based gateway credentials, the key-level default vault role is the aperture, per-vault roles are exceptions, key-level overrides apply broadly, and per-vault overrides apply narrowly.

1allowed = principal RBAC allows the action2          and scope-mode rules allow the bucket/vault/path/action3          and gateway budget preflight allows estimated cost

Scope	Behavior
`user_access`	Personal-key mode. No gateway vault role, default role, or selected vault list is configured. After the principal user's normal RBAC allows an action, the credential may proceed, still subject to enabled state, expiry, budgets, and credential identity.
`vault_allowlist`	App/service-key mode. Requires a key-level default vault role and selected vaults. The default role and key-level overrides apply to every selected vault. Optional per-vault role assignments and per-vault overrides replace or narrow behavior for one selected vault.
`global`	Admin/service-key mode. Requires an admin/service principal and a key-level default vault role. The default role applies across gateway bucket bindings. Optional per-vault role assignments and overrides handle exceptions. Principal RBAC remains the ceiling.

Secure default

For vault_allowlist and global, credentials without an enabled default vault role are denied even when the principal user has normal vault access. For vault_allowlist, a vault must also be selected. For user_access, the principal's Vaulthalla RBAC is enough and no gateway role row is expected.

Vault Roles And Overrides

Each role-based gateway credential has one default vault role. The role uses the same filesystem permission model as ordinary Vaulthalla vault roles. Optional default/key-level overrides apply to every selected vault for vault_allowlist and every gateway bucket binding for global.

Per-vault role assignments are optional exceptions. If a selected or globally bound vault has an enabled per-vault assignment, that role replaces the key default role for that vault. Per-vault overrides apply after key-level overrides; when the same permission and glob appear in both places, the per-vault override wins.

S3 action	RBAC-style permission gate
List buckets, head bucket, list objects	Vault list permission on the bucket root or requested prefix.
HEAD/GET object and copy source	Vault read permission on the object path.
PUT, copy destination, multipart write/complete	Vault write or overwrite permission on the object path.
Delete object and multi-delete	Vault delete permission on each object path.

Deny overrides win according to the filesystem policy evaluator. The principal user's normal RBAC is always evaluated separately, so a gateway key role cannot widen the user's own Vaulthalla authority.

Principal Assignment

Non-admin users can create gateway credentials only for themselves. Creating or updating a credential whose principal differs from the actor requires the explicit admin.s3_gateway.assign_principal permission; super-admins have it through the built-in full S3 Gateway permission set.

CLI Examples

Create credentials:

1# Personal full-access key, bounded by the user's normal vault permissions.2vh s3-gateway creds create laptop --scope user-access --json3 4# Single-bucket backup key. The default role applies to the selected vault.5vh s3-gateway creds create backup \6  --scope vault-allowlist \7  --default-role contributor \8  --selected-vault archive \9  --json10 11# Multi-vault read-only analytics key.12vh s3-gateway creds create analytics \13  --scope vault-allowlist \14  --default-role reader \15  --selected-vault photos \16  --selected-vault reports \17  --json18 19# Global admin service key. Requires admin permission and a default role.20vh s3-gateway creds create gateway-ops --scope global --user admin --default-role reader --json

Inspect, update, and revoke:

1vh s3-gateway creds list2vh s3-gateway creds scope backup show3vh s3-gateway creds scope backup set --scope vault-allowlist4vh s3-gateway creds scope backup allow-vault archive --read --write5vh s3-gateway creds scope backup revoke-vault archive6vh s3-gateway creds revoke VH...

The allow-vault shorthand and boolean create flags are compatibility paths. At save time, Vaulthalla converts them into selected vaults, a default role when it can infer one, and per-vault role exceptions only when needed. New automation should use the default-role and selected-vault model, with creds role assign only for per-vault exceptions.

Assign per-vault role exceptions and path overrides:

1vh s3-gateway creds role assign backup --vault archive --role reader2vh s3-gateway creds role list backup3vh s3-gateway creds role override add backup \4  --vault archive \5  --pattern "/exports/private/*" \6  --permission download \7  --effect deny8vh s3-gateway creds role override list backup --vault archive9vh s3-gateway creds role override remove backup --vault archive 4210vh s3-gateway creds role revoke backup --vault archive

The role commands write s3_gateway_credential_vault_role_assignment and s3_gateway_credential_vault_role_override rows directly. They are exception tools, not the primary selected-vault list. Boolean create flags and creds scope allow-vault are CLI/API shorthand that writes the selected-vault, default-role, and per-vault exception tables.

Local/cache budget accounting is off by default. Enable it only when a gateway credential should consume key budgets for pure local buckets, metadata-only requests, cache hits, and sync-deferred local-first writes/deletes:

1vh s3-gateway creds create backup --enforce-budget-for-local-requests2vh s3-gateway creds scope backup set --enforce-budget-for-local-requests3vh s3-gateway creds scope backup set --no-enforce-budget-for-local-requests

Web Console Workflow

In Admin -> S3 Gateway:

Open the credentials section.
Create a credential and choose the effective principal, description, expiry, and scope mode.
Copy the secret access key immediately; it is revealed only once.
Save scope edits after changing mode, expiry, description, or local budget enforcement.
For vault_allowlist, choose a default vault role and select one or more vaults.
For global, choose a default vault role; selected vaults are hidden because gateway bucket bindings define the vault set.
Add default path overrides when every selected/bound vault should share the rule.
Add per-vault role exceptions or per-vault path overrides only when one vault should differ.
Revoke keys that should no longer authenticate downstream S3 clients.

The web console exposes Count local/cache hits against gateway request budgets for the same enforce_budget_for_local_requests setting.