Managing Fusionauth

FusionAuth Management Skill

Safely read and audit FusionAuth — the developer-focused identity and access management platform.

MANDATORY: Discovery-First Pattern

Always discover tenants, applications, and identity providers before performing targeted queries. Never guess tenant or application IDs.

Phase 1: Discovery

#!/bin/bash

fa_api() {
    local endpoint="$1"
    local method="${2:-GET}"
    curl -s -X "$method" \
         -H "Authorization: $FUSIONAUTH_API_KEY" \
         -H "Content-Type: application/json" \
         "${FUSIONAUTH_URL}/api/${endpoint}"
}

echo "=== FusionAuth Status ==="
curl -s "${FUSIONAUTH_URL}/api/status" | jq '.'

echo ""
echo "=== Tenants ==="
fa_api "tenant" | jq -r '.tenants[] | "\(.id)\t\(.name)\t\(.configured)"' | column -t

echo ""
echo "=== Applications ==="
fa_api "application" | jq -r '.applications[] | "\(.id)\t\(.name)\t\(.active)\t\(.tenantId)"' | column -t

echo ""
echo "=== Identity Providers ==="
fa_api "identity-provider" | jq -r '.identityProviders[]? | "\(.id)\t\(.name)\t\(.type)\t\(.enabled)"' | column -t

echo ""
echo "=== Themes ==="
fa_api "theme" | jq -r '.themes[]? | "\(.id)\t\(.name)\t\(.insertInstant)"' | column -t

echo ""
echo "=== Webhooks ==="
fa_api "webhook" | jq -r '.webhooks[]? | "\(.id)\t\(.url)\t\(.global)\tEvents: \(.eventsEnabled | keys | length)"' | column -t

Phase 1 outputs: Tenant list, applications, identity providers, themes, webhooks — only reference these in subsequent operations.

Anti-Hallucination Rules

• NEVER guess tenant or application IDs — always discover in Phase 1
• NEVER assume identity provider names — always list first
• NEVER fabricate theme or webhook IDs — always list before querying
• ONLY read and list — never create, update, or delete without explicit request

Safety Rules

• READ-ONLY by default: GET requests only — tenants, applications, users, themes, webhooks, audit logs
• MASK sensitive data: Redact API keys, client secrets, HMAC secrets, and user passwords
• FORBIDDEN without explicit request: POST/PUT/DELETE to tenants, applications, users; key generation; password changes
• NEVER print API keys: Always redact key values in output

Core Helper Functions

#!/bin/bash

fa_api() {
    local endpoint="$1"
    local method="${2:-GET}"
    curl -s -X "$method" \
         -H "Authorization: $FUSIONAUTH_API_KEY" \
         -H "Content-Type: application/json" \
         "${FUSIONAUTH_URL}/api/${endpoint}"
}

# Search users
fa_search_users() {
    local query="$1"
    local max="${2:-25}"
    curl -s -X POST \
         -H "Authorization: $FUSIONAUTH_API_KEY" \
         -H "Content-Type: application/json" \
         -d "{\"search\":{\"queryString\":\"${query}\",\"numberOfResults\":${max}}}" \
         "${FUSIONAUTH_URL}/api/user/search"
}

# Tenant-scoped API call
fa_api_tenant() {
    local tenant_id="$1"
    local endpoint="$2"
    curl -s -H "Authorization: $FUSIONAUTH_API_KEY" \
         -H "X-FusionAuth-TenantId: $tenant_id" \
         -H "Content-Type: application/json" \
         "${FUSIONAUTH_URL}/api/${endpoint}"
}

Common Operations

Tenant Configuration

#!/bin/bash
TENANT_ID="${1:?Tenant ID required — discover via Phase 1}"

echo "=== Tenant Details ==="
fa_api "tenant/${TENANT_ID}" | jq '.tenant | {
    id: .id,
    name: .name,
    configured: .configured,
    issuer: .issuer,
    login_config: {
        require_authentication: .loginConfiguration.requireAuthentication
    },
    email_config: {
        host: .emailConfiguration.host,
        port: .emailConfiguration.port,
        security: .emailConfiguration.security,
        verification_required: .emailConfiguration.verifyEmail
    },
    jwt_config: {
        access_token_ttl: .jwtConfiguration.timeToLiveInSeconds,
        refresh_token_ttl: .jwtConfiguration.refreshTokenTimeToLiveInMinutes,
        refresh_token_usage: .jwtConfiguration.refreshTokenUsagePolicy
    },
    password_validation: .passwordValidationRules,
    rate_limit: .rateLimitConfiguration
}'

echo ""
echo "=== Tenant MFA Configuration ==="
fa_api "tenant/${TENANT_ID}" | jq '.tenant.multiFactorConfiguration'

echo ""
echo "=== External Identifier Config ==="
fa_api "tenant/${TENANT_ID}" | jq '.tenant.externalIdentifierConfiguration | {
    authorization_grant_timeout: .authorizationGrantIdTimeToLiveInSeconds,
    change_password_timeout: .changePasswordIdTimeToLiveInSeconds,
    email_verification_timeout: .emailVerificationIdTimeToLiveInSeconds,
    setup_password_timeout: .setupPasswordIdTimeToLiveInSeconds
}'

Application Configuration

#!/bin/bash
APP_ID="${1:?Application ID required — discover via Phase 1}"

echo "=== Application Details ==="
fa_api "application/${APP_ID}" | jq '.application | {
    id: .id,
    name: .name,
    active: .active,
    tenant_id: .tenantId,
    verification_strategy: .verificationStrategy,
    oauth_config: {
        client_id: .oauthConfiguration.clientId,
        client_secret: "*** REDACTED ***",
        authorized_origins: .oauthConfiguration.authorizedOriginURLs,
        authorized_redirects: .oauthConfiguration.authorizedRedirectURLs,
        logout_url: .oauthConfiguration.logoutURL,
        enabled_grants: .oauthConfiguration.enabledGrants,
        require_pkce: .oauthConfiguration.requireClientAuthentication
    },
    registration_config: .registrationConfiguration,
    login_config: .loginConfiguration
}'

echo ""
echo "=== Application Roles ==="
fa_api "application/${APP_ID}" | jq -r '.application.roles[]? | "\(.id)\t\(.name)\t\(.description // "N/A")\tDefault:\(.isDefault)\tSuper:\(.isSuperRole)"' | column -t

Theme Management

#!/bin/bash
echo "=== All Themes ==="
fa_api "theme" | jq -r '.themes[] | {
    id: .id,
    name: .name,
    default: (.defaultMessages != null),
    insert_instant: .insertInstant,
    last_update: .lastUpdateInstant
}'

THEME_ID="${1:-}"
if [ -n "$THEME_ID" ]; then
    echo ""
    echo "=== Theme Templates: $THEME_ID ==="
    fa_api "theme/${THEME_ID}" | jq '.theme | {
        name: .name,
        has_stylesheet: (.stylesheet != null and .stylesheet != ""),
        templates: (to_entries | map(select(.key | test("^(oauth|email|account)"))) | map(.key) | sort)
    }'
fi

Webhook Configuration

#!/bin/bash
echo "=== All Webhooks ==="
fa_api "webhook" | jq -r '.webhooks[] | {
    id: .id,
    url: .url,
    global: .global,
    connect_timeout: .connectTimeout,
    read_timeout: .readTimeout,
    ssl_certificate: (if .sslCertificate then "configured" else "none" end),
    events_enabled: (.eventsEnabled | to_entries | map(select(.value == true)) | map(.key))
}'

echo ""
echo "=== Webhook Event Summary ==="
fa_api "webhook" | jq -r '.webhooks[] | "\(.url)\tEvents: \(.eventsEnabled | to_entries | map(select(.value == true)) | length)"' | column -t

User Management & Audit

#!/bin/bash
SEARCH="${1:?Search term required}"

echo "=== User Search: $SEARCH ==="
fa_search_users "$SEARCH" | jq -r '.users[]? | {
    id: .id,
    email: .email,
    username: .username,
    name: "\(.firstName // "") \(.lastName // "")",
    active: .active,
    verified: .verified,
    two_factor_enabled: (.twoFactor.methods | length > 0),
    insert_instant: .insertInstant,
    last_login: .lastLoginInstant,
    registrations: [.registrations[]? | {app_id: .applicationId, roles: .roles}]
}'

echo ""
echo "=== Audit Log (recent 20) ==="
fa_api "system/audit-log?numberOfResults=20&sortField=insertInstant&sortOrder=desc" | jq -r '.auditLogs[]? | "\(.insertInstant)\t\(.user.email // .user.loginId // "system")\t\(.reason)\t\(.data.attributes // "N/A")"' | column -t

echo ""
echo "=== Login Records ==="
fa_api "system/login-record/export?limit=20" 2>/dev/null | jq -r '.loginRecords[]? | "\(.instant)\t\(.userId)\t\(.applicationId)\t\(.ipAddress)"' | column -t || echo "Login records endpoint may vary by version"

Output Format

Present results as a structured report:

Managing Fusionauth Report
══════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Counter-Rationalizations

Common Pitfalls

• API key scope: API keys can be tenant-scoped or global — tenant-scoped keys return 401 for other tenants
• Multi-tenant header: Use X-FusionAuth-TenantId header to scope requests to a specific tenant
• User search syntax: Search uses Elasticsearch query string syntax — special characters must be escaped
• Theme inheritance: Custom themes inherit from the default theme — missing templates fall back to default
• Webhook retry: Failed webhooks are retried with exponential backoff — check webhook event logs for delivery status
• Application roles vs groups: Roles are per-application; groups are global to tenant — use roles for app-specific authorization
• JWT signing keys: Each application can have its own signing key — verify key configuration per app
• Lambda functions: FusionAuth uses Lambdas (JavaScript functions) for token customization — review Lambda code for security