Clients & Identities

OAuth clients and mock identities are managed in the MinuteMail web dashboard, behind GitHub login. This page walks through registering a client and creating identities linked to your mailboxes. For the OAuth protocol itself, see OAuth Flow.

Accessing the page

1. Log in to MinuteMail
2. Open the Identity Providers page from the main navigation

The page lists all OAuth clients in your account. Each client card shows its client ID, secret, provider, and redirect URIs, and can be expanded to manage its identities.

Registering an OAuth client

In the Create a new OAuth client form:

Field	Required	Description
Name	Yes	Display name shown on the consent screen (e.g. “My App Dev”)
Provider type	Yes	google, github, apple, facebook, or custom
Provider label	Only for custom	Text shown above the client name on the consent screen. Predefined types default to “Google”, “GitHub”, etc.
Redirect URIs	Yes (at least one)	Exact-match URIs your app may be redirected back to (e.g. http://localhost:3000/callback)

The provider type determines the logo rendered on the consent screen — a Google-styled client shows the Google logo, and so on. Use custom with your own label to impersonate any other provider.

On creation you receive:

• Client ID — public identifier (prefixed mc_), used in authorize requests
• Client secret — secret (prefixed cs_) used at token exchange

Copy both — you’ll need them to configure your app. The secret remains visible on the client card in the dashboard and can be copied from there at any time.

Redirect URI rules

• At least one redirect URI is required
• Matching is exact — http://localhost:3000/callback and http://localhost:3000/callback/ are different URIs, and query strings are part of the match
• The redirect_uri sent to the authorize and token endpoints must exactly equal one of the registered URIs

Managing clients

• Rotate secret — generates a new client secret. The old secret stops working immediately; update your app after rotating
• Delete — removes the client (confirmation required). Its identities remain, but flows for this client will fail until re-registered

Creating mock identities

Expand a client card and use the identity form:

Field	Required	Description
Mailbox address	Yes	One of your active MinuteMail mailboxes, selected from the dropdown or typed. The address must exist in your account
Username	No	Defaults to the local part of the mailbox address (before @)
Name	No	Display name; defaults to the username
Avatar URL	No	Picture URL returned by userinfo

An identity is what your app “sees” as the logged-in user: its mailbox address becomes the email claim, the username becomes preferred_username, and the name becomes name in userinfo and ID tokens. Emails your app sends to that address arrive in the linked MinuteMail mailbox, where you can read them from the mailboxes page.

New identities are active immediately. When an authorize request comes in for a client, the first active identity (oldest created) for that client is pre-selected on the consent screen.

Managing identities

• Delete — removes the identity (confirmation required). Tokens already issued for it continue to work until they expire, but new flows will select the next active identity

Quotas

Each plan caps the number of mock identities you can create (mock_identities). The dashboard shows your current usage, and creation fails with a limit error when the cap is reached — delete unused identities or upgrade your plan to continue.