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 bearer token, revocable individually, optionally expiring (you choose a lifetime at creation, or none). Can be scope-restricted via allowed_scopes; stored server-side as a SHA-256 hash. Issued at /me/api-keys in the user portal.

Authorization: Bearer plur_sk_abcd1234...

• Use for: every MCP client that authenticates programmatically.
• Lifecycle: revoke from /me/api-keys if compromised. Keys with an expiry trigger a warning email 7 days before they lapse (when SMTP is configured).

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

2. JWT

30-day session tokens, primarily for the browser admin UI. Issued after OIDC/SAML/GitHub/GitLab login. There is no silent refresh — when the token expires, the user re-runs the login flow.

• Use for: admin browser UI.
• Not for agents: expiry interrupts long-running automation, and JWTs are not individually revocable — the only revocation mechanism is rotating the org-wide JWT_SECRET (an out-of-band runbook: back up .env, set the new secret, move the old one to JWT_SECRET_PREVIOUS for a graceful overlap window, restart). A leaked JWT therefore forces an org-wide rotation event. If per-credential revocation is a requirement, use API keys.

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

Configured from the admin dashboard (/admin/oidc-providers). 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. Configured from the admin dashboard (/admin/saml-providers). 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: set an expiry.
6. Copy the token immediately — you won’t see it again.

Configuring an MCP client

The Enterprise MCP transport is SSE: clients connect to GET /sse and post tool calls to /messages. For clients that support remote SSE servers directly:

{
  "mcpServers": {
    "plur-enterprise": {
      "type": "sse",
      "url": "https://plur.your-org.com/sse",
      "headers": {
        "Authorization": "Bearer plur_sk_..."
      }
    }
  }
}

For local @plur-ai/mcp installs pointing at Enterprise as a remote store, use the MCP tool:

plur_stores_add url="https://plur.your-org.com/sse"
                token="plur_sk_..."
                scope="group:your-org/your-team"

or the CLI equivalent, plur init-remote --url https://plur.your-org.com --token plur_sk_....

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

Multi-factor authentication

MFA is your IdP’s job: when OIDC/SAML/GitHub/GitLab is the active identity provider, its MFA policy applies. There are no local password accounts in PLUR Enterprise. API keys are not MFA-protected by design; their security comes from rotation, revocability, and least-scope.

Auditing

Authentication events are recorded in the audit_log table (with pseudonymized user IDs). See Audit log.