Guide
Service Account vs OAuth for Email Access
Two models give software access to email, and people mix them up constantly. A service account is the app's own identity, authenticating with a key and acting without a person present. User OAuth makes the app act on behalf of a human who consented. Each fits different jobs, and choosing wrong means either an impossible consent flow or an over-privileged key. This guide draws the line and shows where per-user OAuth — the Nylas model — is the simpler default.
Written by Hazik Director of Product Management
Command references used in this guide: nylas auth login, nylas auth config, and nylas auth whoami.
What is the difference between a service account and user OAuth?
A service account is a non-human identity the application uses to authenticate as itself, typically with a private key, and act with permissions granted to the app directly. User OAuth, by contrast, has a person consent so the app acts on their behalf with a token tied to their account. The first answers “the app needs access”; the second answers “the app needs access to this user's mailbox.”
Both Google and Microsoft expose this split. Microsoft names it directly: application permissions versus delegated permissions, where application permissions run without a signed-in user and delegated permissions act as one. Google's equivalent is a service account (optionally with domain-wide delegation) versus a per-user OAuth grant.
When should you use each?
Use a service account when no user is present and the job must run anyway: a nightly archiver reading all mailboxes, a provisioning task creating calendars before employees log in, or a daemon sending from a shared system address. These need an identity that exists independent of any person, with access granted at the app or admin level.
Use user OAuth when the access is to a specific person's mailbox and that person can consent — which describes most products. A CRM logging a rep's threads, a scheduler booking from a user's calendar, or an assistant triaging someone's inbox all act as that user. The table contrasts the two so the requirement, not habit, picks the model.
| Aspect | Service account | User OAuth (Nylas) |
|---|---|---|
| Acts as | The application | A consenting user |
| User present | No | Yes (connects once) |
| Credential | App key (guard it) | Per-user grant |
| Blast radius | All authorized mailboxes | One mailbox per grant |
| Revocation | Admin / rotate key | User revokes grant |
Why is per-user OAuth the simpler default?
Per-user OAuth is simpler because it matches how most products actually work: a user signs up, connects their mailbox, and the app acts as them. There's no app-wide key that, if leaked, exposes every account — each grant reaches one mailbox and the user can revoke it. Nylas implements this model across six providers, so a single nylas auth login connects a user whether they're on Gmail or Outlook.
The security math favors it. A service-account key is a high-value target because it unlocks many mailboxes; a per-user grant limits any compromise to one inbox. Reserve service accounts for the genuine no-user-present jobs, and use per-user OAuth for everything customer-facing. For headless setups, the CLI still authenticates without a browser using nylas auth config --api-key.
# Per-user OAuth: one consent, one grant scoped to that mailbox
nylas auth login --provider google
# Headless / CI: configure with an API key instead of a browser flow
nylas auth config --api-key "$NYLAS_API_KEY"
nylas auth whoami --jsonNext steps
- Google domain-wide delegation — service-account impersonation in depth
- OAuth scopes for email — scoping whichever model you choose
- Email API authentication methods — the full auth picture
- Refresh token management — keeping a grant alive
- Full command reference — every flag and subcommand documented