Glossary

The dozen terms this wiki uses precisely.

Vendor — the company behind provider APIs (deepl, amazon). Owns providers in the catalog. Vendors and Providers

Provider — one concrete API product of a vendor (deepl_api, amazon_translate); the unit credentials are stored against.

Catalog — the versioned YAML describing vendors, providers, schemas, capabilities, and policies; read-only over the API, identical for everyone. Its version string travels as catalog_version.

Credential — one stored record: an encrypted secret object plus open configuration, owned by a user, an organization, or the platform.

Credential schema / configuration schema — the provider's JSON Schemas for the secret and non-secret parts of a credential. Provider Schemas

Ownership level (owner type) — who a credential belongs to: user, organization, or platform. The catalog decides per provider which levels may exist. Core Concepts

Default — the one credential per (provider, owner) that resolve picks; at most one active default per scope. Defaults and Lifecycle

Resolve — the service-plane operation answering "which credential should this user's translation run on", walking USER → ORGANIZATION → PLATFORM. Returns plaintext.

Reveal — the operator-plane operation showing one credential's plaintext to a named human; separately scoped, mandatorily attributed, audited before answered. Reveal

Mask (masked_credentials) — the redacted form every read returns: recognizable, unusable. Personal Credentials

Plane — one of the two API surfaces: user plane (/v1/*, exchange JWTs) and service plane (/internal/v1/*, client-credentials tokens with scopes). User Plane Tokens · Service Plane Tokens

Scope — the service-plane permission unit: provider-credentials.invoke / .admin / .reveal; none implies another.

Exchange token — the short-lived user JWT minted for exactly this service (audience: provider-credentials-service).

Organization manager — a caller whose raw org role is in JWT_ORG_MANAGER_ROLES (default owner/admin); the only identity that may read or write organization credentials.

Soft delete / recovery window — deletion hides the record instantly; ciphertext survives a few days (default 5) until physical purge. Defaults and Lifecycle

Optimistic locking (version) — every mutation names the version it read; stale writes lose with 409. Errors and Conventions

Audit event — the immutable record every consequential action leaves; secrets never included. Audit Events

Correlation id — the request id threading client call → service logs → audit trail; yours if you send it.