Technical client guide

RFC in practice — remote, loopback, PKCE, rotating refresh. Fast path: Quick Start.

For building the flow from scratch or with an OAuth library. Overview: Building a client. Notifique runs OAuth 2.1 with mandatory PKCE on every authorization code exchange, plus Dynamic Client Registration (DCR) at POST /oauth/register. Issuer: https://api.notifique.dev. Login and consent live in the Notifique dashboard. Your app opens the authorize URL in the browser and handles the callback — you do not build consent UI.

Client types

Type	Secret	Use when	Token endpoint auth
Public	No	SPA, mobile, CLI, MCP host	PKCE + `none`
Confidential	Yes	Web app with backend	PKCE + `client_secret_basic`

PKCE is always required — even for confidential clients.

Recommended paths

Fixed registration vs DCR — pre-register known apps; use DCR at runtime for MCP/CLI when redirect/port is unknown upfront.
Remote vs local — HTTPS callback with server session vs loopback http://127.0.0.1:<port>/callback.

Scopes

Declare the minimum at registration and authorize. See Scopes.

Request encoding

Endpoint	Preferred Content-Type
`POST /oauth/register`	`application/json`
`POST /oauth/token`	`application/x-www-form-urlencoded`
`POST /oauth/revoke`	`application/x-www-form-urlencoded`

Confidential clients use HTTP Basic (client_id:client_secret) on token/revoke.

Generating PKCE and state

import { createHash, randomBytes } from 'node:crypto';

function base64url(input) {
  return Buffer.from(input).toString('base64url');
}

const codeVerifier = base64url(randomBytes(64));
const codeChallenge = base64url(
  createHash('sha256').update(codeVerifier).digest(),
);
const state = base64url(randomBytes(24));

Remote: persist state and codeVerifier in the user session before redirect. Local: keep in memory while the loopback server runs.

Pre-registered remote client

Fixed HTTPS redirect, e.g. https://example.com/oauth/callback. Register as confidential. Store client_secret securely — shown once. Treat missing code, mismatched state, or error query params as failures.

curl -X POST 'https://api.notifique.dev/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -d 'grant_type=authorization_code&code=AUTH_CODE&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&code_verifier=CODE_VERIFIER'

Local client (loopback)

Public client, bind 127.0.0.1 or [::1] — never 0.0.0.0.

Do not prefetch /oauth/authorize server-side. The user must see the consent screen in a browser.

curl -X POST 'https://api.notifique.dev/oauth/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "My CLI",
    "redirect_uris": ["http://127.0.0.1/oauth/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none",
    "scope": "email:send"
  }'

Close the loopback server after success or timeout.

Rotating refresh tokens

Each successful refresh returns a new refresh_token. The old one stops working.

Serialize refresh per grant. Persist the new refresh atomically. Parallel workers refreshing the same old token can revoke the entire grant.

curl -X POST 'https://api.notifique.dev/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&client_id=CLIENT_ID&refresh_token=rt_...'

Call `/v1` with the access token

JWT (~15 min, EdDSA). Optional offline validation via GET /.well-known/jwks.json.

Revoke access

Revoke the refresh token — JWT access tokens are not individually revocable.

curl -X POST 'https://api.notifique.dev/oauth/revoke' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -d 'token=rt_...&token_type_hint=refresh_token'

Workspace: Settings → Team → Connected apps.

Simple guides

Learn more

Workspaces

OAuth 2.1

AI and no-code

BYOK

Changelog

Platform API

Account

API Keys

Billing

Credits

Team

Metadata

OAuth

Webhooks

Deliveries

Logs

Workspaces

Technical client guide

Client types

Recommended paths

Scopes

Request encoding

Generating PKCE and state

Pre-registered remote client

Local client (loopback)

Rotating refresh tokens

Call `/v1` with the access token

Revoke access

Next steps

​Client types

​Recommended paths

​Scopes

​Request encoding

​Generating PKCE and state

​Pre-registered remote client

​Local client (loopback)

​Rotating refresh tokens

​Call /v1 with the access token

​Revoke access

​Next steps

Client types

Recommended paths

Scopes

Request encoding

Generating PKCE and state

Pre-registered remote client

Local client (loopback)

Rotating refresh tokens

Call `/v1` with the access token

Revoke access

Next steps