API Authentication

The Formael Management API supports two authentication methods. Every request must include one of them in the Authorization header.

Management Tokens (fml_mgmt_*)

Management tokens are the primary auth method for programmatic access - CI/CD pipelines, Terraform providers, internal tooling, and automated scripts.

Creating a token

1. Open the dashboard → Settings → API Keys
2. Click Create API Key
3. Choose a label and select the token's role (see Role scoping below)
4. Optionally set an expiry date
5. Copy the plaintext token - it is shown exactly once

Alternatively, create tokens via the API itself (requires an existing JWT session):

curl -X POST https://api.formael.com/manage/v1/api-keys \
  -H "Authorization: Bearer <your-keycloak-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"label": "ci-deploy", "role": "admin"}'

Using a token

curl https://api.formael.com/manage/v1/agents \
  -H "Authorization: Bearer fml_mgmt_..."

Token format

All management tokens begin with fml_mgmt_. They are SHA-256 hashed at rest - if you lose the plaintext key, revoke it and create a new one.

Keycloak JWT (Dashboard)

Keycloak JWTs are issued by the Formael dashboard OAuth2 flow. They are suitable for user-facing integrations where an interactive login is acceptable.

JWTs are required for a small number of privileged operations that cannot be delegated to management tokens (creating/revoking management tokens, inviting members, SSO configuration). These endpoints are marked JWT only in the API reference.

Role Scoping

Every request runs with the permissions of the token's assigned role. Roles follow the principle of least privilege:

Anti-escalation rule: A token's role cannot exceed the role of the user who created it. An admin user cannot issue an owner-scoped token.

Assign the minimum role required for each token. A CI pipeline that only reads IEC stats should use viewer, not admin.

Security Best Practices

• Never commit tokens to source control. Use environment variables or a secrets manager.
• Set expiry dates on tokens used in CI/CD. Rotate them on a schedule.
• One token per service. Avoid sharing tokens across systems - it prevents targeted revocation.
• Revoke immediately if a token is exposed. Use DELETE /manage/v1/api-keys/:id.
• Scope to minimum role. Don't use owner-role tokens for read-only operations.

Token Rotation

Use rotation instead of immediate revocation when you need to replace a token without a hard cutover - for example, updating CI/CD secrets across multiple environments.

# Rotate a token - creates a successor and returns its plaintext
curl -X POST https://api.formael.com/manage/v1/api-keys/<id>/rotate \
  -H "Authorization: Bearer <jwt>"

What happens:

1. A new token is created with the same role and label.
2. The old token remains valid for 7 days (the rotation overlap window).
3. After 7 days, the old token is automatically retired - any request using it receives 401 Unauthorized.

Update your secrets during the overlap window, then let the old token expire. Only one rotation per token can be in flight - attempting a second rotation while one is pending returns 409 Conflict.

Token Revocation

# List tokens
curl https://api.formael.com/manage/v1/api-keys \
  -H "Authorization: Bearer <jwt>"
 
# Revoke a specific token
curl -X DELETE https://api.formael.com/manage/v1/api-keys/<id> \
  -H "Authorization: Bearer <jwt>"

Revocation is immediate. In-flight requests using the revoked token will receive 401 Unauthorized.