Tenants, projects, API keys

Upwarden’s access model has three nested objects. Knowing where each one lives lets you map your CI / SCM topology onto Upwarden’s policy and audit surfaces cleanly.

Tenant

A tenant is the top-level boundary — typically one per customer. Tenants own their own policy defaults, audit log, blocklist overrides, and tier (Free / Team / Org / Enterprise). Membership is on the tenant; an individual user can belong to multiple tenants.

Project

A project is a partition inside a tenant — typically one per repository, microservice, or CI pipeline. Projects inherit policy from the tenant and can tighten the policy further (never loosen). The project is the unit your API key is scoped to. See the Policy overrides guide for how per-tenant and per-project policy tightening works.

API key

An API key (vk_...) authenticates each request from a package manager. The key is scoped to one project (and through it, one tenant). The audit log records the apiKeyId on every row, so a failure in one ecosystem doesn’t make you grep through unrelated traffic.

How it maps to your stack

You have	Map to
One company, one CI org	One tenant.
Many independent repos	One project per repo. One key per project.
Polyglot repos (multiple ecosystems)	One project, one key per ecosystem. The key is the discriminator on the audit row.
Multi-tenant SaaS deployments	One tenant per customer. The project model inside each tenant is the customer’s call.

Audit attribution

Every install (and every blocked install) lands one or more audit_log rows scoped to the project’s tenant, with the apiKeyId stamped. The audit row is the canonical forensic record — a breach investigation, a SIEM integration, or just “why did my install fail” reads the same row.

What’s next

• Quickstart — wire your first package manager at the project key.
• Configuration reference — the operator’s env-var surface.