Auth and Token Bootstrap
The auth and token bootstrap feature defines how Inbox Manager accepts trust from auth.inbox-manager.com and applies it to every API request.
It gives you account-based authorization so each call runs for the right account and role.
Why This Matters
This feature verifies token identity and scope before business handlers run, keeping authorization strict and predictable. It also preserves a clear boundary between auth-domain token issuance and Inbox Manager endpoints while keeping account and role checks consistent across protected routes.
Core Flow
The client signs in on auth.inbox-manager.com, obtains a token, and derives an account token when needed. Inbox Manager verifies issuer, audience, signature, and required claims, then executes requests for the token’s account and role; invalid or incomplete tokens are rejected before feature logic runs.
Operations
| Operation | Endpoint | Purpose |
|---|---|---|
| Sign in (external) | POST https://auth.inbox-manager.com/auth/sign-in |
Authenticate user and start token lifecycle |
| OAuth token issue (external) | POST https://auth.inbox-manager.com/oauth2/token |
Issue tokens for public or backend clients |
| Account token derivation (external) | POST https://auth.inbox-manager.com/api/accounts/:account_id/token |
Mint account-scoped token for API calls |
| JWKS discovery (external) | GET https://auth.inbox-manager.com/.well-known/jwks.json |
Fetch signing keys for JWT verification |
| OIDC discovery (external) | GET https://auth.inbox-manager.com/.well-known/openid-configuration |
Fetch OAuth/OIDC metadata for clients |
| Subscription owner pass-through | GET /api/subscriptions and related /api/subscriptions* |
Run owner subscription and plan actions through authorized proxy routes |
Key Data and State
| Claim | Role in Inbox Manager |
|---|---|
uid |
Identifies the acting user |
app |
Identifies application id in the token |
acc |
Selects account for authorized operations |
role |
Constrains account-level capabilities |
aud |
Must match expected Inbox Manager audience |
iss |
Must match configured token issuer |
Failure Modes and Controls
Invalid signatures, issuer/audience mismatches, and missing required claims cause immediate rejection instead of implicit fallback behavior. Token/account mismatches on account-scoped routes are blocked to prevent cross-account access, and auth-domain dependency failures do not bypass verification requirements.
Related
Account, Membership, 01-auth-and-token-bootstrap, 10-auth-backend-admin-flow.