API Authentication

TigerTrust supports multiple authentication methods depending on your use case.

Authentication Methods

Method	Use Case	Format
API Key	Agent communication, CI/CD integrations	`X-Agent-API-Key` header
Session	Dashboard/browser access	Cookie-based session
OAuth 2.0	SSO with Google, Azure AD	OAuth flow

API Key Authentication

API keys are the primary authentication method for programmatic access.

Key Types

Type	Prefix	Purpose
Agent	`ak_`	Agent-to-collector communication
Public	`ck_`	Public API access

Creating an API Key

Navigate to Settings → API Keys in the dashboard
Click Create API Key
Select key type (Agent or Public)
Set expiration (optional)
Copy the key - it won't be shown again

Using API Keys

Include the API key in the X-Agent-API-Key header:

curl -X GET "https://api.tigertrust.io/api/certificates" \
  -H "X-Agent-API-Key: ak_your_api_key_here"

Or use Bearer token format:

curl -X GET "https://api.tigertrust.io/api/certificates" \
  -H "Authorization: Bearer ak_your_api_key_here"

Key Validation

API keys are validated against:

Existence: Key must exist in the database
Active status: Key must not be deactivated
Expiration: Key must not be expired
Revocation: Key must not be revoked
Type: Key type must match the required scope

Workspace Context

All API requests operate within a workspace context.

Workspace Header

Specify workspace for multi-workspace accounts:

curl -X GET "https://api.tigertrust.io/api/certificates" \
  -H "X-Agent-API-Key: ak_your_api_key_here" \
  -H "X-Workspace-ID: ws_123456"

If not specified, the default workspace is used.

Session Authentication

For browser-based access, TigerTrust uses secure HTTP-only cookies.

Login Flow

# Login
curl -X POST "https://api.tigertrust.io/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your_password"}'

# Response includes session cookie
# Set-Cookie: connect.sid=...; HttpOnly; Secure; SameSite=Strict

Session Details

Duration: 7 days
Storage: PostgreSQL session store
Security: HTTP-only, Secure, SameSite=Strict cookies

OAuth 2.0 / SSO

TigerTrust supports OAuth 2.0 with:

Google Workspace
Azure Active Directory
Okta
Custom SAML providers

Google OAuth Flow

1. Redirect to: GET /api/auth/google
2. User authenticates with Google
3. Callback to: GET /api/auth/google/callback
4. Session created, user redirected to dashboard

Two-Factor Authentication

When 2FA is enabled:

# Initial login returns 2FA token
POST /api/auth/login
Response: {"requires2FA": true, "token": "2fa_token_here"}

# Submit 2FA code
POST /api/auth/verify-2fa
Body: {"token": "2fa_token_here", "code": "123456"}

Error Responses

Status	Error Code	Description
401	UNAUTHORIZED	Missing or invalid credentials
401	TOKEN_EXPIRED	API key has expired
401	KEY_REVOKED	API key has been revoked
403	FORBIDDEN	Valid auth but insufficient permissions
403	WORKSPACE_ACCESS_DENIED	No access to specified workspace

Rate Limiting

API requests are rate-limited per API key:

Tier	Requests/Minute	Requests/Hour
Free	60	1,000
Pro	300	10,000
Enterprise	1,000	50,000

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067200

Best Practices

Never commit API keys - Use environment variables
Rotate keys regularly - Set expiration dates
Use minimal scopes - Request only needed permissions
Monitor key usage - Review audit logs
Revoke unused keys - Clean up old integrations