OAuth Setup
Secure OAuth 2.0 integration for connecting email and calendar accounts.
What is OAuth?
OAuth 2.0 is an industry-standard protocol for secure authorization. Instead of asking for your password, OAuth allows neurals to access your email and calendar accounts with your explicit permission.
Important: We never see or store your passwords. OAuth provides secure, revocable access that you control.
Gmail OAuth Setup
Step 1: Get Authorization URL
Click "Connect Gmail" in your dashboard, or use the API:
GET /api/integrations/gmail/authorize
# Returns authorization URL:
{
"authorization_url": "https://accounts.google.com/o/oauth2/auth?...",
"state": "random-state-string"
}Step 2: Authorize Access
You'll be redirected to Google's secure OAuth page where you:
- • Sign in to your Google account
- • Review the permissions neurals is requesting
- • Grant access (you can revoke anytime)
Step 3: Exchange Authorization Code
After authorization, Google redirects back with an authorization code. neurals exchanges this for access and refresh tokens:
POST /api/integrations/gmail/connect
{
"auth_code": "4/0AbCDef..."
}
# Returns:
{
"success": true,
"status": "connected"
}Step 4: Automatic Token Refresh
neurals automatically refreshes expired tokens using the refresh token. You don't need to reconnect unless you revoke access.
Google Calendar OAuth
The process for Google Calendar is similar to Gmail:
- Click "Connect Calendar" in your dashboard
- Authorize access via Google's OAuth page
- neurals exchanges the code for tokens
- Calendar access is now configured!
Permissions & Scope
Gmail Permissions
- • gmail.readonly: Read email metadata (subjects, senders, dates)
- • gmail.send: Send emails on your behalf
- • gmail.modify: Organize emails (labels, categories)
Calendar Permissions
- • calendar.readonly: Read calendar events
- • calendar.events: Access meeting details
Managing Connected Accounts
View Connected Accounts
Check which accounts are connected:
GET /api/integrations
# Returns:
{
"integrations": [
{
"provider": "gmail",
"connected": true,
"connected_at": "2024-01-15T10:00:00Z",
"status": "active"
}
]
}Revoke Access
You can revoke access at any time from your dashboard or directly from Google Account settings. Revoking access immediately disconnects the integration.
Security Best Practices
- • Always use HTTPS for OAuth redirects
- • Verify state parameter to prevent CSRF attacks
- • Store refresh tokens securely
- • Implement token refresh logic
- • Monitor for suspicious activity