Authentication

PLUR Enterprise supports six authentication paths. Every agent/CLI client uses an API key. Browser users use the IdP your org standardised on.

Quick recommendation matrix

Client	Use this	Why
Claude Code	API key	Long-lived; survives restarts; no browser flow.
Cursor	API key	No MCP-side OAuth UI.
VS Code (generic MCP)	API key	Same.
Codex (CLI)	API key	CLI tool; no browser context.
RooCode	API key	VS Code extension; same as VS Code.
OpenClaw (@plur-ai/claw)	API key	Agent runtime; needs always-on credential.
Browser admin UI	OIDC / SAML / GitHub / GitLab	Human → browser → IdP → session cookie.
SCIM provisioning (Okta / Azure AD)	SCIM bearer token	Server-to-server; managed by IdP admin.

The methods

1. API key

Long-lived (default 1 year, rotatable), can be scope-restricted, server-side SHA-256 hash. Issued at /me/api-keys in the admin UI.

Authorization: Bearer plur_sk_abcd1234...

• Use for: every MCP client that authenticates programmatically.
• Lifecycle: rotate yearly; revoke from /me/api-keys if compromised.
• Auto-warning email at 25 days before expiry.

Code: src/auth/api-key.ts + src/auth/middleware.ts.

2. JWT

24-hour rotating tokens, primarily for the browser admin UI. Issued after OIDC/SAML/GitHub/GitLab login; refreshed silently while the session cookie is valid.

• Use for: admin browser UI.
• Not for agents: 24h expiry would interrupt long-running automation; API keys are the right fit.

Code: src/auth/token.ts (HS256, dual-secret rotation).

3. OIDC

Standard OIDC. Works with:

• Google Workspace
• Microsoft Entra (Azure AD)
• Okta (in OIDC mode)
• Auth0
• Keycloak
• Any RFC-compliant OIDC provider

Configure at /admin/sso. You’ll need:

• Client ID
• Client secret
• OIDC discovery URL

Recommended for organisations with existing Google Workspace or Microsoft IdP.

Code: src/admin/oidc/.

4. SAML 2.0

For orgs with a SAML IdP — Shibboleth, ADFS, some Okta/Azure configurations. Configure at /admin/sso. You’ll need:

• IdP metadata XML
• IdP certificate

Recommended for established SAML infrastructure.

Code: src/admin/saml/ (uses @node-saml/node-saml).

5. GitHub OAuth

For orgs that want GitHub identities. Useful when team membership maps to GitHub orgs/teams — group memberships sync automatically from GitHub into PLUR’s permission graph.

Code: src/github/oauth.ts + src/github/sync.ts.

6. GitLab OAuth

Same model as GitHub, for GitLab orgs. Supports self-hosted GitLab.

Code: src/gitlab/.

7. SCIM 2.0

Not a login method — a provisioning protocol. Your IdP (Okta, Azure AD) creates and disables users automatically via SCIM API calls. Tokens managed at /admin/scim/tokens.

Code: src/scim/. See SCIM provisioning.

How to issue an API key

1. Log in to /me (the user portal).
2. Open API keys tab.
3. Click New key.
4. Optional: scope-restrict the key (e.g., only group:platform/*).
5. Optional: shorten the lifetime.
6. Copy the token immediately — you won’t see it again.

Configuring an MCP client

For HTTP/SSE clients (PLUR Enterprise-hosted):

{
  "mcpServers": {
    "plur": {
      "transport": "streamable_http",
      "url": "https://plur.your-org.com/mcp",
      "headers": {
        "Authorization": "Bearer plur_sk_..."
      }
    }
  }
}

For local @plur-ai/mcp clients pointing at Enterprise as a remote store:

plur stores add \
  --name your-org \
  --url https://plur.your-org.com \
  --token plur_sk_...

Both paths land at the same endpoint with the same permission model.

Multi-factor authentication

When OIDC/SAML is the active IdP, MFA is handled there. Local admin accounts (the one created from PLUR_ADMIN_PASSWORD) support TOTP — enable from /me/security. API keys are not MFA-protected by design; their security comes from rotation and least-scope.

Auditing

Every successful and failed auth attempt is recorded in the audit_log table. Failed-auth spikes trigger an alert if a webhook is configured. See Audit log.