Authentication¶

The Mayo ASPM API supports two authentication methods: API keys for machine-to-machine access and JWT tokens for user-session-based access.

API Key authentication¶

API keys are long-lived credentials for programmatic access. They are the recommended method for scripts, CI/CD pipelines, and integrations.

Usage¶

curl https://mayoaspm.com/api/findings \
  -H "Authorization: Bearer mayo_ak_a1b2c3d4..."

Or using the X-API-Key header:

curl https://mayoaspm.com/api/findings \
  -H "X-API-Key: mayo_ak_a1b2c3d4..."

When to use API keys¶

Scenario	Use API key?
CI/CD pipeline	Yes
Airflow DAG	Yes
Custom script	Yes
cURL from terminal	Yes
Browser-based app	No — use JWT
Interactive session	No — use JWT

Creating and managing keys¶

See API Keys for full details on creating, revoking, and rotating keys.

JWT authentication¶

JWT (JSON Web Token) authentication is used for browser-based sessions. When a user logs in to Mayo ASPM, they receive a JWT that authenticates subsequent API calls.

Obtaining a JWT¶

JWTs are issued through the login flow:

curl -X POST https://mayoaspm.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Using a JWT¶

curl https://mayoaspm.com/api/findings \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Token refresh¶

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token:

curl -X POST https://mayoaspm.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

When to use JWTs¶

Scenario	Use JWT?
Single-page application (SPA)	Yes
Custom dashboard	Yes
Short-lived scripts with user context	Yes
Long-running automation	No — use API key

Comparison¶

Feature	API Key	JWT
Lifetime	Days to years (configurable)	1 hour (access), 7 days (refresh)
Permissions	Scoped at creation time	User's full permissions
Revocation	Immediate via settings	Logout or wait for expiry
Audit trail	Tracks key name	Tracks user identity
Best for	Automation	Interactive sessions

Permission model¶

API key permissions¶

API keys have explicit permission scopes set at creation time:

scans:read, scans:write, findings:read, findings:write,
policies:read, policies:write, projects:read, projects:write,
tickets:read, tickets:write, admin

A request that requires a permission the key doesn't have returns 403 Forbidden.

JWT permissions¶

JWT tokens carry the authenticated user's role-based permissions:

Role	Permissions
Viewer	Read access to all resources
Editor	Read + write access to findings, tickets
Policy Editor	Editor + policy management
Project Admin	Editor + project management
Admin	Full access

Security considerations¶

API keys¶

Store in secrets managers, never in code
Set expiry dates
Rotate every 90 days
Monitor "last used" timestamps
Use separate keys per integration

JWTs¶

Store access tokens in memory (not localStorage)
Use httpOnly cookies for refresh tokens
Implement token refresh logic
Handle 401 responses gracefully

Error responses¶

Status	Meaning
`401 Unauthorized`	Missing or invalid credentials
`403 Forbidden`	Valid credentials but insufficient permissions

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