Architecture

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

The hierarchy#

1
2
3
4
5
6
7
8

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 for the full type and scope matrix.

Admin roles#

Three role tiers, increasing in scope:

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.