Authentication

Overview

IncidentFox supports multiple authentication methods:

Team Tokens - For programmatic team access
Admin Tokens - For organization administration
OIDC/SSO - For user authentication via identity provider

Team Tokens

Team tokens provide access scoped to a specific team within an organization.

Token Format

tokid.toksecret

tokid - Token identifier (public)
toksecret - Token secret (keep secure)

Usage

Include in the Authorization header:

curl -X GET https://api.incidentfox.ai/api/v1/config/me/effective \
  -H "Authorization: Bearer tokid.toksecret"

Obtaining Tokens

Team tokens are issued by your organization admin:

Admin logs into Web UI
Navigates to Admin Console > Teams
Selects team and clicks Generate Token
Token is displayed once - save it securely

Token Permissions

Team tokens can:

Read team configuration
Update team configuration
Trigger investigations
View investigation history

Team tokens cannot:

Access other teams
Modify organization settings
Create/delete teams

Admin Tokens

Admin tokens provide organization-wide access.

Permissions

Admin tokens can:

Manage all teams
View audit logs
Configure organization settings
Create/revoke team tokens

Usage

curl -X GET https://api.incidentfox.ai/api/v1/admin/teams \
  -H "Authorization: Bearer admin.tokensecret"

OIDC/SSO Authentication

For user-based authentication via your identity provider.

Configuration

Configure OIDC in organization settings:

{
  "oidc": {
    "issuer": "https://login.company.com",
    "client_id": "incidentfox-app",
    "client_secret": "vault://secrets/oidc-secret"
  }
}

Supported Providers

Google Workspace
Azure AD
Okta
Auth0
Generic OIDC

JWT Token Usage

After OIDC authentication, use the JWT:

curl -X GET https://api.incidentfox.ai/api/v1/config/me/effective \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Identifying the Caller

Use the /auth/me endpoint to identify the authenticated user/team:

curl -X GET https://api.incidentfox.ai/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "role": "team",
  "auth_kind": "team_token",
  "org_id": "org-acme",
  "team_node_id": "team-platform",
  "subject": null,
  "email": null,
  "can_write": true,
  "permissions": ["team:read", "team:write"]
}

For OIDC users:

{
  "role": "user",
  "auth_kind": "oidc_jwt",
  "org_id": "org-acme",
  "team_node_id": null,
  "subject": "user@company.com",
  "email": "user@company.com",
  "can_write": true,
  "permissions": ["admin:read", "admin:write"]
}

Token Security

Treat tokens like passwords. Never commit to version control or share publicly.

Best Practices

Store securely - Use secrets managers
Rotate regularly - Rotate tokens periodically
Use least privilege - Use team tokens when admin isn’t needed
Monitor usage - Review audit logs for anomalies
Revoke unused - Revoke tokens when no longer needed

Token Revocation

Admins can revoke tokens:

curl -X POST https://api.incidentfox.ai/api/v1/admin/tokens/revoke \
  -H "Authorization: Bearer admin.token" \
  -H "Content-Type: application/json" \
  -d '{"token_id": "tokid"}'

Error Handling

Invalid Token

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired token"
  }
}

Expired Token

{
  "error": {
    "code": "token_expired",
    "message": "Token has expired"
  }
}

Insufficient Permissions

{
  "error": {
    "code": "forbidden",
    "message": "Token does not have permission for this operation"
  }
}

API Documentation

Agent API

Config API

Overview

Team Tokens

Token Format

Usage

Obtaining Tokens

Token Permissions

Admin Tokens

Permissions

Usage

OIDC/SSO Authentication

Configuration

Supported Providers

JWT Token Usage

Identifying the Caller

Token Security

Best Practices

Token Revocation

Error Handling

Invalid Token

Expired Token

Insufficient Permissions

Next Steps

Run Agent

Get Config

​Overview

​Team Tokens

​Token Format

​Usage

​Obtaining Tokens

​Token Permissions

​Admin Tokens

​Permissions

​Usage

​OIDC/SSO Authentication

​Configuration

​Supported Providers

​JWT Token Usage

​Identifying the Caller

​Token Security

​Best Practices

​Token Revocation

​Error Handling

​Invalid Token

​Expired Token

​Insufficient Permissions

​Next Steps

Run Agent

Get Config

Overview

Team Tokens

Token Format

Usage

Obtaining Tokens

Token Permissions

Admin Tokens

Permissions

Usage

OIDC/SSO Authentication

Configuration

Supported Providers

JWT Token Usage

Identifying the Caller

Token Security

Best Practices

Token Revocation

Error Handling

Invalid Token

Expired Token

Insufficient Permissions

Next Steps