flareauth

name	flareauth
description	Operate a FlareAuth deployment through its Management API using Restish. 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, or readiness through the standardized OpenAPI contract.

FlareAuth

Use Restish against the FlareAuth Management API. The public Management API base path is:

/api/management

The OpenAPI contract is generated by the server and served at:

/api/management/openapi.json

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.

Then run one local command yourself. The script derives a deployment-specific Restish profile name from the origin, writes the Restish profile through Restish, syncs the OpenAPI contract, and starts the browser authorization flow:

~/.agents/skills/flareauth/scripts/authorize.sh AUTH_ORIGIN

The script only calls Restish commands; it must not write Restish config files itself. It auto-accepts Restish's detected setup defaults. The only expected interactive step is the browser administrator login started by restish auth-header.

Example:

~/.agents/skills/flareauth/scripts/authorize.sh https://AUTH_ORIGIN

This derives a profile name from the deployment hostname. Pass an explicit second argument only when the user asks for a custom profile name.

If the skill is installed under a different agent home, use that installed skill path. The source copy in this repository is:

./skills/flareauth/scripts/authorize.sh AUTH_ORIGIN

Use the generated profile name in every command below. In examples, replace PROFILE_NAME with that generated or explicitly provided profile.

Authentication

FlareAuth has a built-in public native client for Restish:

client_id: flareauth-cli
redirect_url: http://localhost:8484/callback
scopes: openid profile email offline_access management:read management:write

The authorization script runs:

restish auth-header PROFILE_NAME

Ask the user to complete the browser login as an administrator. Do not ask the user to copy or paste bearer tokens. The script suppresses token output and lets Restish store the OAuth token in its local auth cache. After authorization, run follow-up commands directly through the same Restish profile:

restish PROFILE_NAME list-applications

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.

Command Style

After api sync, prefer generated operation commands because they match the OpenAPI operationIds:

restish PROFILE_NAME get-readiness
restish PROFILE_NAME list-applications
restish PROFILE_NAME get-application app_123

When generated commands are awkward or unavailable, use Restish generic verbs with resource paths:

restish get PROFILE_NAME/applications
restish get PROFILE_NAME/applications/app_123
restish post PROFILE_NAME/applications < app.json
restish patch PROFILE_NAME/applications/app_123 < patch.json
restish delete PROFILE_NAME/applications/app_123

Use -o json when another tool or script will consume the result.

Common Operations

For application configuration, distinguish the FlareAuth deployment origin from the consuming product origin. AUTH_ORIGIN is where the Management API lives; APP_ORIGIN is the product application's origin used in OIDC redirect URIs. Never copy placeholder callback domains into a real application.

Create an 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"],
  "firstParty": true,
  "trusted": true
}
JSON

Update an application:

restish PROFILE_NAME update-application app_123 \
  -H "Content-Type: application/json" \
  -o json <<'JSON'
{
  "name": "Customer Portal Updated"
}
JSON

Create a draft connector:

restish PROFILE_NAME create-connector \
  -H "Content-Type: application/json" \
  -o json <<'JSON'
{
  "slug": "google",
  "providerType": "social",
  "providerId": "google",
  "displayName": "Google",
  "enabled": false
}
JSON

Check deployment readiness:

restish PROFILE_NAME get-readiness -o json

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.