# Authentication

The Capsule Security platform provides secure authentication through multiple methods to ensure your AI agent management remains protected.

## Authentication Methods

### Email Magic Link (Auth0)

The platform supports passwordless authentication using Auth0's magic link feature:

1. **Login Flow**
  - Navigate to the login page
  - Enter your email address
  - Check your email for a secure magic link
  - Click the link to authenticate
  - You'll be redirected to the platform dashboard
2. **Session Management**
  - Sessions are maintained using secure HTTP-only cookies
  - Session duration: 24 hours (configurable)
  - Automatic session refresh on activity


### Single Sign-On (SSO)

For enterprise customers, we support custom SSO providers:

1. **Supported Protocols**
  - SAML 2.0
  - OAuth 2.0 / OpenID Connect
  - Active Directory Federation Services (ADFS)
2. **Setup Process**
  - Contact support@capsule.security to initiate SSO setup
  - Provide your Identity Provider (IdP) metadata
  - Configure attribute mappings
  - Test authentication flow with support team
  - Deploy to your organization


## API Authentication

### Session Cookie Authentication

When accessing the API through the web interface, authentication is handled automatically via session cookies:


```javascript
// API calls automatically include session cookie
const response = await fetch('/api/v1/agents', {
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json'
  }
});
```

### Bearer Token Authentication

For programmatic API access, use Bearer tokens:


```bash
# Include the token in the Authorization header
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.capsule.security/api/v1/agents
```

## Session Information

Retrieve current session details:


```javascript
GET /api/v1/auth/session

Response:
{
  "userId": "user_123",
  "email": "user@example.com",
  "name": "John Doe",
  "tenants": {
    "tenant_1": {
      "roles": ["admin", "viewer"]
    }
  },
  "tenantIds": ["tenant_1", "tenant_2"],
  "organization": {
    "id": "org_123",
    "name": "Acme Corp"
  }
}
```

## Multi-Tenant Access

The platform supports multi-tenant architecture:

- Users can belong to multiple tenants
- Role-based access control per tenant
- Tenant isolation for data security
- Cross-tenant agent visibility (with permissions)


## Security Best Practices

1. **Session Security**
  - Sessions expire after 24 hours of inactivity
  - Secure, HTTP-only cookies prevent XSS attacks
  - CSRF protection on all state-changing operations
2. **Password Requirements** (for SSO providers)
  - Minimum 12 characters
  - Mix of uppercase, lowercase, numbers, and symbols
  - Regular password rotation policies
3. **API Token Management**
  - Rotate API tokens regularly
  - Use environment variables for token storage
  - Never commit tokens to version control
  - Implement token expiration policies


## Troubleshooting

### Common Issues

1. **Magic Link Not Received**
  - Check spam/junk folders
  - Verify email address is correct
  - Ensure your domain allows emails from auth0.com
  - Contact support if issues persist
2. **SSO Login Failures**
  - Verify SSO configuration with your IT team
  - Check IdP is properly configured
  - Ensure user has proper permissions
  - Review SAML assertions for errors
3. **Session Expiration**
  - Sessions expire after 24 hours
  - Re-authenticate when prompted
  - Check browser cookie settings


### Support

For authentication issues or SSO setup:

- Email: support@capsule.security
- Include your organization ID and error messages
- SSO setup typically requires 2-3 business days