flareauth

name: flareauth description: Operate a FlareAuth deployment and guide product OIDC client integration. Use this when an agent needs to inspect or change FlareAuth applications, connectors, users, roles, organizations, API resources, webhooks, security settings, branding, sign-in settings, readiness, or configure public SPA, public native, confidential web, or device-authorization OIDC clients.

FlareAuth

Use this skill for two related tasks:

• Operating a FlareAuth deployment through the Management API.
• Guiding product OIDC clients that integrate with FlareAuth.

For the full Management API Restish command list, read references/restish-commands.md.

Setup

First identify the deployment origin you are operating. Use the exact auth origin from the user, deployment repository, Cloudflare Worker, or /api/configz response. Do not guess a production domain from the product name.

On first use, an agent must establish the FlareAuth deployment origin before it changes anything. AUTH_ORIGIN is the FlareAuth deployment origin, such as a production custom domain or a workers.dev origin.

If the user did not provide AUTH_ORIGIN, inspect the deployment repository or Cloudflare Worker configuration when available. If neither is available, ask for the deployment origin before continuing.

For deployment operations, authorize a Restish profile first. The command sequence is in references/restish-commands.md; use that reference rather than reconstructing Restish commands from memory.

Authentication

FlareAuth has a built-in public native client named flareauth-cli for Restish Management API automation. It is not the product OIDC device-login client, and system-managed applications such as flareauth-cli must not be modified.

Ask the user to complete browser login when Restish authorization starts. Do not ask the user to copy or paste bearer tokens. The authorization helper suppresses token output and lets Restish store OAuth tokens in its local auth cache.

Do not use product OIDC client credentials for Management API automation. The Management API accepts an admin browser session or a bearer token issued to flareauth-cli; non-admin users receive 403.

If the user has already authorized this Restish profile, they can rerun the same authorization script to refresh the local profile and cached auth.

OIDC Client Integration

Use the FlareAuth deployment issuer for product clients:

AUTH_ORIGIN/api/auth

Prefer discovery metadata instead of hard-coding endpoints:

AUTH_ORIGIN/api/auth/.well-known/openid-configuration

Common product scopes are openid profile email. Add offline_access only when the client needs refresh tokens. Management scopes are reserved for the system CLI client and are not accepted on ordinary product clients.

Choose the client type by where the application runs:

All authorization-code clients should use PKCE where their OIDC library supports it. Public clients use tokenEndpointAuthMethod: none; confidential clients use a client secret.

Creating OIDC Clients

Authorize and sync a PROFILE_NAME before running these examples. Distinguish the FlareAuth deployment origin from the consuming product origin. AUTH_ORIGIN is where FlareAuth runs; APP_ORIGIN is the product application's origin used in OIDC redirect URIs.

Create a public SPA application:

restish PROFILE_NAME create-application \
  -H "Content-Type: application/json" \
  -o json <<'JSON'
{
  "name": "Customer Portal",
  "slug": "customer-portal",
  "clientType": "public_spa",
  "redirectUris": ["https://APP_ORIGIN/oidc/callback"],
  "postLogoutRedirectUris": ["https://APP_ORIGIN/signed-out"],
  "corsOrigins": ["https://APP_ORIGIN"],
  "allowedGrantTypes": ["authorization_code", "refresh_token"],
  "allowedScopes": ["openid", "profile", "email", "offline_access"],
  "firstParty": true,
  "trusted": true
}
JSON

Create a public native authorization-code application:

restish PROFILE_NAME create-application \
  -H "Content-Type: application/json" \
  -o json <<'JSON'
{
  "name": "Desktop App",
  "slug": "desktop-app",
  "clientType": "public_native",
  "redirectUris": ["com.example.desktop:/callback", "http://127.0.0.1:8484/callback"],
  "allowedGrantTypes": ["authorization_code", "refresh_token"],
  "allowedScopes": ["openid", "profile", "email", "offline_access"],
  "firstParty": true,
  "trusted": true
}
JSON

Create a public native device-login application:

restish PROFILE_NAME create-application \
  -H "Content-Type: application/json" \
  -o json <<'JSON'
{
  "name": "Runner CLI",
  "slug": "runner-cli",
  "clientType": "public_native",
  "redirectUris": ["com.example.runner:/callback"],
  "allowedGrantTypes": ["urn:ietf:params:oauth:grant-type:device_code"],
  "allowedScopes": ["openid", "profile", "email", "offline_access"],
  "firstParty": true,
  "trusted": true
}
JSON

Create a confidential web application:

restish PROFILE_NAME create-application \
  -H "Content-Type: application/json" \
  -o json <<'JSON'
{
  "name": "Admin Backend",
  "slug": "admin-backend",
  "clientType": "confidential_web",
  "redirectUris": ["https://ADMIN_ORIGIN/oidc/callback"],
  "postLogoutRedirectUris": ["https://ADMIN_ORIGIN/signed-out"],
  "allowedGrantTypes": ["authorization_code", "refresh_token"],
  "allowedScopes": ["openid", "profile", "email", "offline_access"],
  "firstParty": true,
  "trusted": true
}
JSON

For confidential clients, store the returned clientSecret immediately. It is shown only once. Add client_credentials only when that backend must act without a user.

Device Authorization Flow

Use device authorization only with public_native clients.

The discovery document advertises the device authorization endpoint and device-code grant when supported:

device_authorization_endpoint: AUTH_ORIGIN/api/auth/device/code
token_endpoint: AUTH_ORIGIN/api/auth/oauth2/token
grant_type: urn:ietf:params:oauth:grant-type:device_code

Device flow:

1. Request a device code from /api/auth/device/code with client_id and scopes such as openid profile email offline_access.
2. Show user_code and verification_uri to the user.
3. The user opens /device, signs in, and approves or denies the request.
4. Poll /api/auth/oauth2/token with the device-code grant.
5. Handle RFC 8628 polling errors: authorization_pending, slow_down, access_denied, and expired_token.
6. On success, consume the OAuth/OIDC token response. openid returns an id_token; offline_access returns a refresh_token.

Device-code request:

curl -sS -X POST "$AUTH_ORIGIN/api/auth/device/code" \
  -H "content-type: application/json" \
  --data '{"client_id":"CLIENT_ID","scope":"openid profile email offline_access"}'

Token polling request:

curl -sS -X POST "$AUTH_ORIGIN/api/auth/oauth2/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  --data-urlencode "client_id=CLIENT_ID" \
  --data-urlencode "device_code=DEVICE_CODE"

For generic OIDC client libraries, prefer discovery metadata and the library's device authorization support.

Guardrails

• Always sync before operating a deployment you have not used recently.
• Always confirm the deployment origin and profile name before making changes.
• Prefer resource nouns and real IDs from list/get responses; do not infer IDs from names.
• System-managed applications such as flareauth-cli must not be deleted or modified.
• Asset upload endpoints use multipart/form-data with a single file field.
• Raw secrets are returned only once on creation or rotation; never expect list/detail responses to reveal secret material.
• For large changes, read current state first, apply the smallest patch, then read back the resource to verify.