Keymaster Developer Documentation

Version: 1.0.0 Base URL: https://keymaster.cloud-monitor.com

Keymaster is an identity broker for the Cloud Monitor platform. It provides shared user authentication, cross-app SSO, and centralized user management for all connected applications.

Quick Links

Quick Start Guide — Get your app authenticating in 5 minutes
Authentication Guide — OAuth2 flows, SSO, provider setup
Token Lifecycle — JWT access tokens, refresh rotation, session management
Server-to-Server — Client credentials grant for backend APIs
Push Notifications — Device registration, sending, delivery receipts
Webhooks — Outbound event delivery, HMAC signatures, retry behavior
API Reference — Complete endpoint documentation

Architecture Overview

Your App (client)
    ↓ redirect
Keymaster Login (branded per app)
    ↓ OAuth2 authorization code
Your App Callback
    ↓ access_token + refresh_token
Your App Backend
    ↓ verify JWT (via JWKS) or POST /token/verify
Protected Resources

Key Concepts

Concept	Description
Tenant	Organization that owns apps. Has its own admin tier and password policy.
App	A registered client application. Gets `client_id` + `client_secret`, configurable auth methods, branding.
User	Global identity (email-based). Can be enrolled in multiple apps across tenants.
SSO Session	Platform-wide "logged in at Keymaster" session (`km_sso` cookie). Log in once, access all enrolled apps.
Access Token	RS256 JWT, short-lived (default 15 min). Carries user_id, email, roles, app_id.
Refresh Token	Opaque string, long-lived (default 30 days). Rotated on every use.
Roles	`user` (base), `manager` (invite/revoke), `admin` (full app control). Custom roles supported.

Well-Known Endpoints

Endpoint	Description
`GET /.well-known/openid-configuration`	OIDC discovery document
`GET /.well-known/jwks.json`	Public keys for JWT verification