Email Auth: OAuth vs API Key vs App Password

What are the three email authentication methods?

Email API authentication splits into three categories: OAuth 2.0 (delegated authorization with scoped tokens), API keys (static credentials for service-level access), and app-specific passwords (generated passwords for legacy protocols). The right choice depends on your provider, access pattern, and security requirements. Most developers end up using OAuth 2.0 because Google and Microsoft mandate it — Google deprecated its less-secure-apps option in September 2024, and Microsoft removed Basic Auth on October 1, 2022.

Each method makes different trade-offs between security, setup complexity, and token management. OAuth tokens expire every 3,600 seconds and require refresh logic. API keys never expire but grant broader access. App passwords are permanent but only work with IMAP/SMTP, not REST APIs.

How does OAuth 2.0 work for email?

OAuth 2.0 is a delegated authorization protocol where the user grants an application limited access to their mailbox without sharing their password. The application receives an access token (valid for 3,600 seconds on Google, 3,600 seconds on Microsoft) and a refresh token (valid for 90 days on Microsoft, indefinitely on Google unless revoked). According to Google's OAuth 2.0 documentation, the protocol supports granular scopes — you can request gmail.readonly without getting gmail.send access.

The setup cost is significant. Google requires a GCP project, OAuth consent screen, client ID, and client secret. Microsoft requires an Azure AD (Entra ID) app registration with tenant ID, client ID, and redirect URI. Token refresh logic adds 20-50 lines of code to any integration. The security payoff: compromised tokens auto-expire, scopes limit blast radius, and users can revoke access anytime.

# OAuth flow with the Nylas CLI (handles token refresh automatically)
nylas auth login you@gmail.com

# Behind the scenes, the CLI:
# 1. Opens a browser for Google OAuth consent
# 2. Receives the authorization code
# 3. Exchanges it for access + refresh tokens
# 4. Stores tokens encrypted in ~/.config/nylas/credentials.json
# 5. Refreshes automatically when the access token expires

How do API keys work for email?

API keys are static credentials that identify and authorize an application at the service level. Unlike OAuth (which represents a specific user's delegation), an API key grants access to all resources the application owns. The Nylas platform uses API keys for server-to-server authentication — one key covers all grants (user accounts) under that application. API keys don't expire unless rotated manually.

The advantage is simplicity: no OAuth dance, no browser redirect, no refresh tokens. Store the key in an environment variable or secret manager and authenticate with a single header. The trade-off is granularity — an API key can't be scoped to one user's mailbox. If leaked, it exposes all accounts under that application until rotated. Best practice: use API keys for backend services and cron jobs, not client-side applications.

# Authenticate with an API key (no browser needed)
nylas auth config --api-key nyk_v0_abc123...

# Works in CI/CD, cron jobs, Docker containers
# No interactive OAuth flow required
# Covers all grants under this Nylas application

How do app-specific passwords work?

App-specific passwords are generated credentials designed for legacy protocols (IMAP, SMTP, POP3) that can't perform an OAuth flow. Apple iCloud requires app-specific passwords for all third-party IMAP access — generated at appleid.apple.com under "Sign-In and Security > App-Specific Passwords." Yahoo generates them under "Account Security > Generate app password." Gmail still supports app-specific passwords for IMAP/SMTP but requires 2-Step Verification to be enabled first — Google removed "Less Secure Apps" (plain password auth) in September 2024.

App passwords don't expire and can't be scoped — they grant full IMAP/SMTP access to the entire mailbox. They exist solely for backward compatibility with tools that predate OAuth. The Nylas CLI handles iCloud and Yahoo authentication internally so you don't need to generate or manage app passwords yourself — the OAuth flow covers both providers.

Which method should you use?

The decision depends on three factors: which provider you're connecting to (Gmail and Outlook mandate OAuth), whether you need user-level or application-level access, and whether your runtime supports interactive browser flows. The table below maps each combination to the right auth method. In practice, most developers end up using OAuth for direct provider APIs or an API key with a unified platform that handles OAuth internally.

How does the Nylas CLI handle authentication?

The Nylas CLI supports two auth modes: nylas auth login (OAuth flow for end-user access) and nylas auth config --api-key (API key for service-level access). The OAuth path opens a browser, completes the consent flow, and stores encrypted tokens locally. The API key path stores the key in ~/.config/nylas/credentials.json with file permissions restricted to your user. Both paths unlock the same CLI commands — email, calendar, contacts, webhooks, and notetaker.

Token refresh happens automatically. When an OAuth access token expires (after 3,600 seconds), the CLI uses the stored refresh token to get a new one without user interaction. This means cron jobs and long-running scripts never hit token expiration errors. The Nylas platform handles provider-specific OAuth quirks internally — Google's consent screen requirements, Microsoft's tenant-specific endpoints, and iCloud's non-standard OAuth implementation.

# Option 1: OAuth (interactive, user-level access)
nylas auth login you@gmail.com
# Opens browser → consent → tokens stored locally

# Option 2: API key (non-interactive, service-level access)
nylas auth config --api-key nyk_v0_abc123...
# No browser needed — works in CI/CD and Docker

# Check current auth status
nylas auth status
nylas auth scopes  # Show granted OAuth scopes

Next steps

Set up authentication with the getting started guide. For Gmail-specific OAuth details, see Gmail OAuth setup. For Microsoft Graph authentication, check Graph API quickstart. To understand how authentication works with shared mailboxes, see shared mailbox management. The full command reference covers all auth subcommands.