OAuth 2.0 + OpenID Connect Identity Provider — let your users sign in to your app with their Zafeguard account.

Overview

Zafeguard is an OpenID Connect Identity Provider. Any third-party application can let users sign in with their Zafeguard account using the OAuth 2.0 Authorization Code flow with PKCE.

This page is for developers building an integration that authenticates Zafeguard users — not for end-users authorizing an app. End-users approve or revoke authorizations from their workspace's Connected apps page in the dashboard.

What you get

A standard OAuth 2.0 / OIDC surface — discovery document, JWKS, authorize, token, userinfo, revocation. Use any compliant OIDC client library (e.g. openid-client, oauth4webapi, Auth0 React SDK, Google's identity-toolkit client) and point it at the Zafeguard issuer.
Workspace-scoped access — your app does not get blanket access to every workspace the user belongs to. Each authorization is for one workspace the user picks on the consent screen; the access token carries a workspace_id claim that determines which workspace you can act on.
RS256-signed JWTs verifiable offline — every access + ID token is signed against the public JWKS so you can verify them without an extra network round-trip to Zafeguard.

The endpoints

Endpoint	Purpose
`GET /.well-known/openid-configuration`	OIDC discovery document. Lists every endpoint, supported scopes, signing algorithm.
`GET /.well-known/jwks.json`	Public signing keys. Verify access + ID tokens against these.
`GET /oauth/authorize`	Browser entry point. Redirects the user to sign in and approve scopes.
`POST /oauth/token`	Exchange an authorization code (or a refresh token) for an access token.
`GET /oauth/userinfo`	Returns identity claims for the access token bearer.
`POST /oauth/revoke`	Revoke a refresh token.

All endpoints sit at the root of api.zafeguard.com (no /v1/ prefix) — they implement the OIDC spec exactly.

High-level flow

1. You register an OAuth app once (one-time setup in your Zafeguard developer dashboard).
   Admin reviews + approves the metadata.

2. You issue a client secret from the developer dashboard (shown once).

3. At runtime, for each user sign-in:

   ┌─ your app ──────────────────────────────────────┐
   │                                                 │
   │  Generate `code_verifier` + `code_challenge`    │
   │  Redirect browser to /oauth/authorize?...       │
   │                                                 │
   └────────────────┬────────────────────────────────┘
                    │
                    ▼ (Zafeguard renders sign-in + consent)
                    │
   ┌─ your app callback ──────────────────────────────┐
   │                                                  │
   │  Receive ?code=…&state=…                         │
   │  POST /oauth/token with code + code_verifier     │
   │  Receive access_token + id_token + refresh_token │
   │  Verify id_token signature against JWKS          │
   │                                                  │
   └──────────────────────────────────────────────────┘

Continue with the Quickstart for runnable code.

Two key differences vs. typical OAuth providers

1. Workspace selection is per-authorization

When a user lands on Zafeguard's consent screen, they pick which one of their workspaces to authorize your app for. Each authorization is independent:

A user who is in two workspaces can authorize your app for one of them and not the other.
They can authorize your app for both workspaces independently — that creates two separate consents, two separate refresh-token chains, and two separate access tokens, each scoped to one workspace.
Revoking access for one workspace does not affect the other.

The access token carries a workspace_id claim. Any workspace-scoped API call your app makes is restricted to that workspace.

2. App registration is reviewed

Your app's name, description, logo, redirect URIs, and requested scopes are reviewed by Zafeguard staff before going live. Once approved, the metadata is locked — to change it (e.g. add a new redirect URI), you ask Zafeguard staff to revert the app to draft, edit, and re-submit for review. Reverting to draft invalidates the client secret and disables the OAuth flow until re-approval.

This keeps Zafeguard's consent screen trustworthy: users can rely on the displayed name + logo matching what they expect.

Standards we follow

OpenID Connect Core 1.0
OAuth 2.0 Authorization Code Grant
PKCE (RFC 7636) — required (code_challenge_method=S256 only; plain is rejected)
OAuth 2.0 Token Revocation (RFC 7009)
JSON Web Key Set (RFC 7517)

Token signing algorithm: RS256 only.

What's next

Quickstart → — register an app, run the full flow end-to-end.
Scopes → — what each scope grants your app permission to do.

Overview

On this page