Introduction to OrgNet

OrgNet is a cloud-hosted identity and access platform that handles authentication, cross-domain single sign-on, role-based access control, and zero-trust security for AI agents — all through a single, consistent API.

Whether you're protecting a new web app, adding SSO across multiple domains, or securing OpenClaw agent actions, OrgNet provides the same foundation: OAuth 2.1 with PKCE, RS256-signed JWTs, and Redis-backed token revocation in under 1ms.

Quick Start

The fastest path to a protected page is three steps:

1. Register your app in the OrgNet dashboard — you'll get a client_id
2. Add the OrgNet SDK to your page
3. Call orgnet.protectPage()

See the 60-second quickstart for full code examples including PHP server-side validation and AI agent authentication.

Identity Model — Person → Identity

OrgNet separates who you are from who you're acting as. This distinction matters when one person belongs to multiple organisations.

• A Person is identified by email address. One login credential, one password.
• An Identity is the person's membership in a specific organisation — carrying their emp_id, org_id, role, and permissions for that org.
• At any moment, exactly one identity is active. The user always sees which org they're operating in.
• Users with multiple org memberships see an org picker at login and can switch context at any time without re-authenticating.

JWT Claims Reference

Every OrgNet Access Token is a signed RS256 JWT. The payload carries standard IETF claims plus OrgNet-specific claims in the orgnet: namespace.

Cross-Domain SSO

OrgNet uses a Master Session Token (MST) stored as an HttpOnly Secure cookie on auth.orgnet.app to enable seamless authentication across all your registered domains.

1. User logs in on any domain → OrgNet issues an MST (8hr TTL) in an HttpOnly cookie
2. User navigates to a different registered domain
3. The OrgNet JS SDK fires a silent POST /token/derive request via a hidden iframe
4. OrgNet validates the MST and issues a fresh, short-lived Access Token scoped to the new app
5. The SDK resolves with the token — the user is authenticated with no prompt

RBAC — Roles & Permissions

OrgNet uses a three-layer access control model:

• Org-level roles — apply across the organisation (e.g. OrgAdmin can manage all apps)
• App-level roles — scoped to a specific registered application
• Resource-level policies (ABAC) — fine-grained per-resource conditions (e.g. user can only edit documents they own)

System Roles (built-in)

Resolved permissions are embedded in the JWT's orgnet:perms claim, so your app can check permissions without a network call:

// JavaScript
if (user.perms.includes('doc:write')) showEditButton();

// PHP
if ($user->hasPermission('doc:write')) { /* show edit button */ }

OpenClaw — AI Agent Integration

OrgNet treats AI agents as Service Accounts — not users. Agents authenticate via the OAuth 2.1 Client Credentials grant, receive short-lived scope-locked tokens, and are subject to per-agent rate limiting and audit logging.

Service Account Setup

1. In the OrgNet dashboard: Org Settings → Service Accounts → Create
2. Choose a name, set the allowed scopes (principle of least privilege)
3. Copy the client_id and client_secret — the secret is shown once and stored hashed
4. Store both in your agent's secrets vault (never in environment variables committed to git)

API Endpoints Overview

Authentication

Direct email + password authentication. Returns MST cookie and access token. Rate limited to 5 attempts per 15 minutes per IP.

Revokes the MST and current access token. Clears the HttpOnly cookie. Propagates logout to all active sessions within 60 seconds.

Creates a new person record. Sends email verification. Accepts: email, password, display_name.

Sends a password reset email with a signed magic link. Always returns 200 — does not reveal whether the email exists.

Applies a new password using a valid reset token. Revokes all existing tokens for the person. Token is single-use, 1-hour expiry.

Switches the active org context. Accepts an identity_id that belongs to the authenticated person. Issues new tokens scoped to the new identity.

OAuth 2.1

Initiates the Authorization Code + PKCE flow. Required params: client_id, redirect_uri, code_challenge, code_challenge_method=S256.

Exchanges an authorization code for tokens, or authenticates a service account via Client Credentials. Supports authorization_code and client_credentials grant types.

Revokes an access or refresh token immediately. Always returns 200 (RFC 7009 compliant — does not reveal whether token existed).

Returns the active status and claims of a token. Restricted to registered clients. Returns {"active": false} for expired or revoked tokens.

Issues a new app-scoped access token from a valid MST. Used by the SDK for silent cross-domain SSO. Validates the requesting domain against the org's registered domains.

User & Identity

Returns the authenticated user's person record, active identity, and resolved permissions. Requires a valid Bearer token.

Lists all active sessions for the authenticated person across all apps and domains. Each session shows app, device, last active time, and a revoke button.

JWKS & Key Rotation

Returns the current and previous RS256 public keys in RFC 7517 format. Cache this response — it changes only on key rotation (every 90 days). Your SDK or PHP package fetches this automatically.

OIDC discovery document. Standard-compliant — any OIDC client library can auto-configure from this endpoint.

Token Revocation

Token revocation in OrgNet is Redis-backed and takes effect in under 1 millisecond. Every token validation checks Redis for the token's jti (JWT ID) before accepting the token.

The following events trigger automatic revocation of all tokens for a person:

• Password reset
• Account suspension by an OrgAdmin
• Explicit logout via POST /auth/logout

Individual tokens can be revoked via POST /oauth/revoke or from the Sessions UI.

SDKs & Libraries

All SDKs share the same API surface and are fully compatible with the JWT structure described above.