Quick Start Guide

Get your app authenticating with Keymaster in 5 minutes.

Prerequisites

• An app registered in the Keymaster Console (you'll need the app_id and client_secret)
• At least one redirect URI configured
• At least one auth provider enabled (password, Google, etc.)

Step 1: Redirect to Keymaster Login

When a user clicks "Sign In" in your app, redirect them to:

https://keymaster.cloud-monitor.com/login
  ?app_id=YOUR_APP_ID
  &redirect_uri=https://yourapp.com/auth/callback

Keymaster shows a branded login page with your app's logo, name, and enabled auth methods.

Step 2: Handle the Callback

After successful authentication, Keymaster redirects back to your redirect_uri with tokens:

https://yourapp.com/auth/callback
  ?access_token=eyJhbGciOiJSUzI1NiIs...
  &refresh_token=a1b2c3d4e5f6...

Step 3: Verify the Access Token

The access token is an RS256-signed JWT. Verify it using Keymaster's public keys:

# Python (using PyJWT)
import jwt
from jwt import PyJWKClient

jwks_client = PyJWKClient("https://keymaster.cloud-monitor.com/.well-known/jwks.json")
signing_key = jwks_client.get_signing_key_from_jwt(access_token)

payload = jwt.decode(
    access_token,
    signing_key.key,
    algorithms=["RS256"],
    issuer="https://keymaster.cloud-monitor.com",
    audience=YOUR_APP_ID,
)

# payload contains:
# {
#   "sub": "user-uuid",
#   "email": "user@example.com",
#   "roles": ["user", "admin"],
#   "name": "Jane Doe",
#   "aud": "your-app-id",
#   "iss": "https://keymaster.cloud-monitor.com",
#   "iat": 1710547200,
#   "exp": 1710548100
# }

// Node.js (using jose)
import { createRemoteJWKSet, jwtVerify } from 'jose';

const JWKS = createRemoteJWKSet(
  new URL('https://keymaster.cloud-monitor.com/.well-known/jwks.json')
);

const { payload } = await jwtVerify(accessToken, JWKS, {
  issuer: 'https://keymaster.cloud-monitor.com',
  audience: YOUR_APP_ID,
});

Step 4: Store Tokens and Refresh

Store both tokens in a durable session store (database, not memory). The access token expires in 15 minutes. Before it expires, refresh it:

import httpx

resp = httpx.post("https://keymaster.cloud-monitor.com/token/refresh", json={
    "refresh_token": stored_refresh_token,
    "app_id": YOUR_APP_ID,
})
data = resp.json()
# {
#   "access_token": "new-jwt...",
#   "refresh_token": "new-refresh-token...",
#   "expires_in": 900
# }

# IMPORTANT: Update BOTH tokens in your session store.
# The old refresh token is now revoked (rotation).

The refresh token is valid for 30 days and rotates on every use. As long as the user is active within the 30-day window, their session never expires.

Step 5: Logout

When the user logs out:

# 1. Revoke the refresh token (best-effort)
httpx.post("https://keymaster.cloud-monitor.com/token/revoke", json={
    "refresh_token": stored_refresh_token,
})

# 2. Destroy local session
session.delete()

# 3. Redirect to Keymaster's branded logout page
redirect("https://keymaster.cloud-monitor.com/sso/logout"
         "?app_id=YOUR_APP_ID"
         "&post_logout_redirect_uri=https://yourapp.com")

What's Next?

• Authentication Guide — Detailed OAuth2 flows, SSO behavior, provider setup
• Token Lifecycle — Refresh rotation, replay detection, session management
• Server-to-Server — Client credentials for backend API calls
• API Reference — Complete endpoint documentation