---
title: Architecture
path: concepts/architecture
status: published
---

# Architecture

ScaiKey is multi-tenant from the ground up. There are five entity types you need to know.

## The hierarchy

```
Partner (prt_…)
   └── Tenant (tnt_…)
         ├── User (usr_…)
         ├── Group (grp_…)
         ├── OrganizationalUnit (ou_…)
         ├── Application (app_…)      ← can also be Partner- or Global-scoped
         ├── IdentityProvider (idp_…)
         └── MCPAgent (agt_…)
```

### Partner

The outermost ownership boundary. A partner is typically a reseller, a business unit, or "ScaiLabs itself" for first-party tenants. Partners hold their own resource limits (`max_tenants`, `max_users_per_tenant`, `max_applications_per_tenant`) and are the unit at which white-labeling and billing relationships sit.

A user typically does not interact with a partner directly — they belong to a tenant, which belongs to a partner.

### Tenant

A tenant is one organization's slice of ScaiKey. Each tenant has:

- Its own users, groups, and organizational units (no cross-tenant visibility by default).
- Its own configured identity providers and federation rules.
- Its own MFA policy, password policy, session timeout (all in the `settings` JSON column).
- Optional branding (logos, colors, custom domain) for its login pages.

Tenants are uniquely addressable by `slug`, which becomes part of OIDC URLs: `/api/v1/auth/tenants/{slug}/oauth/authorize`.

### User

A person (or service account) inside a tenant. Users authenticate via password + optional MFA, or via federation from an external IdP. The full attribute set is AD-compatible (display name, title, department, manager, custom attributes) so SCIM imports and exports are lossless.

### Group

A collection of users (and, optionally, other groups — nesting is supported). Groups are used for:

- Application assignment (an entire group gets access to an app).
- Role attribution via group membership.
- Authorization decisions in downstream apps that consume ScaiKey tokens.

### Application

An OAuth/OIDC client. **Applications are the most important concept after tenants** because they're what every other system in the ScaiLabs ecosystem registers as. See [Applications](/docs/scaikey/concepts/applications) for the full type and scope matrix.

## Admin roles

Three role tiers, increasing in scope:

| Role | Sees / manages |
|---|---|
| `tenant_admin` | One tenant: its users, groups, apps, MFA settings |
| `partner_admin` | All tenants under one partner |
| `super_admin` | Everything in the platform |

`GLOBAL`-scoped applications (next page) generally need `super_admin` to register; `TENANT`-scoped apps can be registered by tenant admins.

## Platform vs tenant endpoints

ScaiKey exposes OIDC endpoints in two flavors:

- **Tenant-scoped:** `/api/v1/auth/tenants/{slug}/oauth/...` — used by apps that belong to one tenant or want users to authenticate within a specific tenant context.
- **Platform-level:** `/api/v1/platform/oauth/...` — used by `GLOBAL`-scoped apps that authenticate users from any tenant. Both flavors return JWTs signed with the same key; they differ in the `iss` claim and the OIDC discovery URL.

Each flavor has its own `.well-known/openid-configuration` discovery document.