OAuth Authentication

Effective 8 October 2026 · Version 1.0

How sign-in and API access work in Indo Mail today (password, bearer tokens, 2-step verification, limited tokens), and the planned OAuth 2.0 and OpenID Connect provider for third-party apps.

1. Summary

Today, Indo Mail has no public OAuth provider. Nobody outside Indo Mail can register an app that asks users for permission to read their mail, and "Sign in with Indo Mail" does not exist yet. The only way to use the API is to sign in as the account owner with a password.

This page explains how that works, which safeguards protect it, and the OAuth 2.0 and OpenID Connect design that we plan to build. Everything in the planned sections is a design, not a promise of dates.

2. How sign-in works today

Part	How it works
Identity	A person signs in with their full address (or username) and a password.
Password rules	Between 8 and 128 characters, with at least one letter and one number.
Password storage	Passwords are stored only as bcrypt hashes. We cannot read them, and we never email them.
Session token	A correct password returns a bearer token, a signed JSON Web Token. It is valid for 7 days. The app sends it as `Authorization: Bearer <token>` on every call.
Rate limiting	Sign-in, sign-up, the second sign-in step and password change are limited to 20 attempts per 15 minutes per client. Failed attempts are recorded in sign-in history.
Disabled accounts	A disabled account, or an account whose business domain is suspended, cannot sign in. Tokens are checked again on use.
Sign-in history	Every sign-in records time, IP address and device. The account owner sees it in Settings, and in the API at `GET /api/auth/activity`.

Treat a bearer token like a password. Anyone who has it can act as you for up to 7 days. If a token leaks, change your password at once.

3. 2-Step Verification (TOTP)

2-Step Verification is live for all accounts. It uses time-based one-time passwords (TOTP), the standard used by authenticator apps. The flow is:

POST /api/auth/2fa/setup returns a secret and an otpauth:// link. Add it to an authenticator app by scanning the QR code or typing the secret.
POST /api/auth/2fa/enable with the six-digit code from the app turns 2-step on.
After that, POST /api/auth/login with a correct password returns {"twoFactor":true,"ticket":"..."} and no token. The ticket is a signed value that lasts 5 minutes and can only be used for the next step.
POST /api/auth/login/2fa with the ticket and a current code returns the bearer token.
POST /api/auth/2fa/disable with the account password turns it off. Each setup, enable, disable and failed code is written to sign-in history.

Passkeys, SMS codes and backup codes are not available yet. They are planned.

4. Limited tokens

Some tokens are deliberately narrow, so that a leak does little harm. These are in use now:

Token	Lasts	Can be used for
Live stream ticket (`POST /api/mail/events-ticket`)	60 seconds	Opening the stream that tells the app about new mail. It cannot read or send anything.
Signed download link (attachments and Drive files)	Short-lived; expires quickly	Downloading one file. The link names the file and the account.
Two-step sign-in ticket	5 minutes	Completing the second step of sign-in only.
Android device token (Web Push registration for the app)	Until sign-out or removal in Settings	Checking for notifications for that device. It cannot open mail.

5. Why not give apps your password?

Sharing a password with an app is a bad idea. The app sees everything the account can do, you cannot limit it, you cannot stop it without changing your password, and it cannot use 2-Step Verification properly. OAuth solves each of these. Until it exists, please do not give your Indo Mail password to any third-party app or website. Indo Mail does not endorse any such app.

6. Planned: OAuth 2.0 and OpenID Connect provider

Planned, not live. We intend to become an OAuth 2.0 authorisation server and an OpenID Connect identity provider, so that other apps can ask a user for limited permission, and so that "Sign in with Indo Mail" works. The design follows current best practice:

Authorisation Code flow with PKCE for all apps, including web, mobile and desktop. The code challenge method will be S256.
No implicit flow and no password grant. Passwords are typed only on indoemail.in.
Redirect addresses must be registered in advance and match exactly. Native apps use app links or loopback addresses.
Users approve the permissions on a consent screen in plain language, and 2-Step Verification is enforced if the user has it on.
Refresh token rotation: each use returns a new refresh token, and re-use of an old one revokes the whole chain.
Client secrets for server-side apps are shown once and stored as hashes.
OpenID Connect adds an ID token with the user's address and name, and a discovery document at /.well-known/openid-configuration.
Tokens are bound to one app and one user. An app can never use another app's token.

7. Planned scopes

Scopes will be narrow. An app asks only for what it needs, and the user can see and remove each one.

Scope	Allows	Sensitivity
openid	Identify the user with a stable ID	Basic
profile	Read display name	Basic
email	Read the user's Indo Mail address	Basic
mail.send	Send mail as the user, but not read it	Restricted
mail.readonly	Read messages and labels	Restricted, needs review
mail.modify	Read, label, archive and delete messages	Restricted, needs review
contacts.readonly	Read contacts	Sensitive
drive.file	Create files and read only files the app created	Sensitive
drive.readonly	Read all Drive files	Restricted, needs review
wallet.request	Create UPI payment requests for the user	Sensitive
ads.read	Read an advertiser's own campaign reports and leads	Sensitive
admin	Manage a business domain, for company administrators only	Restricted, needs review
offline_access	Receive a refresh token	Basic

Scopes that give access to mail or all files will not be available to apps until the app and its developer have passed review.

8. Planned token lifetimes

Item	Planned lifetime
Authorisation code	10 minutes, single use
Access token	1 hour
Refresh token	30 days of inactivity, rotated at each use
ID token	1 hour
User consent	Until the user withdraws it

9. Planned app review

Any app that asks for a restricted scope must be reviewed before more than 100 users can approve it. Review will check:

The developer's identity, and for companies, the registration details.
A clear privacy notice that follows the Digital Personal Data Protection Act, 2023 and the Digital Personal Data Protection Rules, 2025.
That every scope asked for is really needed.
That data is stored securely, is not sold, is not used for advertising and is not used to train AI models.
For apps that read mail, a security assessment by an independent reviewer.

10. Planned revocation

Users can see every connected app in Settings and remove it with one click. The app's tokens stop working at once.
Changing the password, or reporting a compromise, revokes all tokens for the account.
Developers can revoke tokens through a revocation endpoint.
We can suspend an app that breaks the Developer Terms. All its tokens are revoked.
If a business turns off third-party apps in the admin console, the apps stop working for everyone in the company.

11. Contact

Questions about authentication, or early access to the planned provider: contact@indoemail.in with the subject "Developer access". Security reports: security@indoemail.in.

INDO CHATS PRIVATE LIMITED, 168, GT Rd, near Aloka Cinema, Shibpur, Howrah, West Bengal 711102, India.