Identity and directory
The directory service is a component of Stacklok Enterprise. For a full comparison of ToolHive Community and Stacklok Enterprise capabilities, see Stacklok Enterprise.
The directory is the platform's record of who your people are and what they are entitled to. Other components ask it rather than keeping their own copies: the MCP gateway asks which connectors a caller may reach, the AI Gateway's budgets are addressed to directory users and groups, and the console's administration screens are views onto it.
What it holds
| Thing | Used for |
|---|---|
| Users | Resolving a token to a person, and addressing per-user budgets |
| Groups and subgroups | Granting connector access, and addressing per-group budgets |
| Identity providers | The upstream services connectors authenticate against |
| Managed secrets | Encrypted storage for the credentials those connections need |
| Virtual API keys | Long-lived keys that stand in for a person's own token |
How identity is resolved
A caller arrives with a token. The directory maps the token's issuer and subject to a user record, then reads that user's group memberships, including groups inherited through subgroups. Downstream components receive the resolved user and group identifiers rather than raw token claims.
A caller with no matching user record resolves to nothing. That is not an error in itself, but controls that key on platform identity will not fire for them, and controls that fail closed will refuse them.
Directory groups are not the same as the OIDC claim groups named in cluster-level authorization policy, and the platform does not keep the two in sync. See The two group models before configuring either.
API surface
Administrative endpoints live under /v1: users, groups, managed-secrets,
connector-identity-providers, connections, and keys. Every authenticated
caller can read their own equivalent under /v1/me, without an administrative
grant.
Administrative routes require the shared platform admin grant. There is no separate role per module, so the same grant covers directory administration and budget administration.
Contents
Users and groups
Create and administer directory users, groups, and subgroups, and understand how inherited membership affects connector access and budgets.
SCIM provisioning
Provision directory users and groups automatically from Okta, Entra ID, or any SCIM 2.0 identity provider.
Identity providers
Register the upstream identity providers that connectors authenticate against, and understand the read-only corporate provider entry.
Managed secrets
Store connector credentials encrypted at rest in the directory, and rotate the key that protects them.
Virtual API keys
Issue long-lived API keys that stand in for a user's own identity, so scripts and CI can reach the gateways without an interactive sign-in.