Workspaces & projects

The hierarchyCopy Anchor Link

Workspace  acme                  people, teams, billing
└── Project  payments-api        one API
    ├── Environment  production  ← payments-api-production
    ├── Environment  staging     ← payments-api-staging
    └── Environment  sandbox

A workspace is an organisation. It owns people, teams and projects, and is the boundary nothing crosses: a client id from another workspace resolves to 404 rather than being operated on.

A project is one API. Project slugs are unique per workspace, not globally — two organisations can both have payments-api.

An environment is where everything real lives. Endpoints, clients, keys and templates all belong to exactly one environment, and none of them are shared between environments. A key issued in staging will not verify against production, because the environment is signed into the key.

Addressing an environmentCopy Anchor Link

<project-slug>-<env-type>     payments-api-production

Because a slug may contain dashes, resolution tries the whole string as a slug first, then falls back to splitting off a trailing environment type.

For session-authenticated REST calls, also send the workspace:

x-tenant: acme

Without it, the lookup falls back to the workspaces you belong to and returns 400 if the address is ambiguous — rather than guessing. API-key callers never need it: they are already scoped to the team owning the key's client.

RolesCopy Anchor Link

Apikee uses three workspace roles.

member is read-only by design — it is the right role for someone who needs to see usage and docs without the ability to mint credentials.

Instance administrators are separate and orthogonal: an admin flag on the user account grants access to /admin, where instance-wide settings live (email, storage, sign-in providers, the AI endpoint, licence). Being a workspace owner does not make you an instance admin.

TeamsCopy Anchor Link

Projects belong to a team within the workspace. For a small installation the single default team is fine; larger ones use teams to keep each group's projects separate.

See Teams & roles.

Choosing a layoutCopy Anchor Link

A few patterns that work:

One project per deployable API. The common case. Environments mirror your deploy stages.

One project per customer-facing surface. If your public API and your partner API have different route sets and different consumers, they are different projects even if one service serves both.

A sandbox environment for trials. Give prospective customers keys in an environment with tight template limits and no production data. Because environment is signed into the key, a sandbox key physically cannot reach production.

DeletingCopy Anchor Link

Deletion is guarded. Removing an environment that still has clients returns 412 rather than cascading — you delete or move the clients first. This is deliberate: an accidental cascade here would revoke live credentials.