Authentication
Learn how to authenticate with Twig AI for both user access and programmatic API access.
User Authentication
Web Application
Access the web application at app.twig.so:
Email/Password: Standard email and password authentication
SSO: Single Sign-On with your organization's identity provider
OAuth: Google, Microsoft, or other OAuth providers
Session Management
Sessions persist across browser sessions
Automatic session refresh
Secure token storage
Logout clears all credentials
API Authentication
For programmatic access to the Twig AI API, you need an API key.
Generating an API Key
Navigate to Settings → API Keys
Click Generate New API Key
Provide a name (e.g., "Production API", "Development")
Select permissions/scopes (if applicable)
Copy and securely store the API key
⚠️ Important: The API key is only shown once. Store it securely.
Using API Keys
Include your API key in the request header:
API Key Best Practices
✅ Do:
Store keys in environment variables
Use different keys for development and production
Rotate keys regularly
Use the minimum required permissions
Monitor key usage in analytics
❌ Don't:
Commit keys to version control
Share keys in public channels
Use the same key across multiple applications
Hardcode keys in your application
API Key Scopes
API keys can be scoped to specific permissions:
Read: View agents, data sources, and interactions
Write: Create and modify agents and data sources
Execute: Make chat/completion requests
Admin: Full administrative access
External API Keys
Twig AI can securely store external API keys for integrations:
Supported External Keys
OpenAI API keys (for custom models)
Anthropic API keys (for Claude)
Pinecone API keys (for custom indexes)
Custom LLM provider keys
Managing External Keys
Navigate to Settings → External API Keys
Click Add External Key
Select the provider
Enter the API key
Keys are encrypted at rest
SSO Integration
For enterprise customers, Twig AI supports Single Sign-On.
Supported Protocols
SAML 2.0: Industry-standard protocol
OAuth 2.0: For Google Workspace, Microsoft 365
OpenID Connect: Modern authentication standard
Setting Up SSO
Contact your account manager or [email protected]
Provide your IdP metadata or configuration
Configure attribute mapping
Test with a pilot group
Enable for all organization users
See SSO Integration for detailed setup instructions.
OAuth Integration
For integrations with third-party services (Google Drive, Microsoft, Slack), Twig AI uses OAuth 2.0.
OAuth Flow
User clicks "Connect [Service]"
Redirected to service authorization page
User grants permissions
Redirected back to Twig AI
Access token securely stored
Token Management
Access tokens are encrypted
Refresh tokens automatically renew access
Revoke access anytime from settings
Tokens are scoped to minimum required permissions
Security Considerations
Token Security
All tokens are encrypted at rest
Transmitted only over HTTPS
Short-lived access tokens
Secure token storage in database
Rate Limiting
API keys are subject to rate limits:
Default: 100 requests per minute
Enterprise: Custom limits available
Monitor usage in dashboard
429 status code when limit exceeded
IP Whitelisting
Enterprise customers can restrict API access by IP:
Whitelist specific IP ranges
Block unauthorized access
Audit access attempts
Troubleshooting
Invalid API Key
Solutions:
Verify the key is correct
Check that the key hasn't been revoked
Ensure proper header format:
Authorization: Bearer YOUR_KEY
Expired Token
Solutions:
Refresh your access token
Re-authenticate
Check token expiration time
Insufficient Permissions
Solutions:
Verify your API key has the required scope
Contact admin to update permissions
Use a key with appropriate access
Next Steps
Learn about Your First Agent
Explore the REST API
Review Security Best Practices
Last updated