Riposte’s hosted authentication keeps provider secrets and consent screens on our side while your product owns the onboarding
experience. Create a short-lived session from your backend, hand the generated link to your user, and let Riposte orchestrate
the provider hand-off before we return control to your application.
Riposte needs the hosted flow to round-trip through these public routes (feel free to front them with your own proxy so long
as traffic still reaches us):
GET /auth/authorizePOST /auth/authorizeGET /providers/{providerName}/callback
If you would rather not expose any of them, move to the advanced authentication flow and manage the
redirects yourself.
When you call POST /auth/sessions, Riposte returns a one-time URL for your user. The flow should look like this:
- Your product launches the hosted link returned from
POST /auth/sessions.
- Riposte drives the provider consent screen (Google, Microsoft, IMAP), generates the PKCE verifier and challenge, and
completes the redirect back to
/providers/{providerName}/callback on your behalf.
- Riposte exchanges the authorization code for tokens, links them to the originating session, and immediately redirects the
browser to the redirect URI associated with that session.
- Your product can poll the Accounts API or subscribe to webhooks to detect the newly connected mailbox. Always provide a
redirectUri when creating the auth session or configure riposte.app.redirectUrl so Riposte knows where to send the user
once the provider handshake finishes.
If Google or Microsoft ever bypass Riposte and land on your product directly, double-check the authorized redirect URIs in the
provider console. The admin portal’s guided provider setup walks through those URLs step by step and flags mismatches so you
can fix them before going live. Review POST /auth/sessions below for the precise payload Riposte expects when you create the
hosted link.
GET /auth/authorize
Render hosted authentication screen
Renders the built-in Riposte authentication experience for a previously created session.
Parameters
In query • Required
Single-use authorization code issued by Riposte.
authsess_01HZY7FN5MSV2S8A1G31RZK8H4
In query • Required
Opaque state generated when the session was created. Used for CSRF protection.
state_1234
Returns
Rendered HTML response for the hosted authentication experience.
Content type: application/json
Status: 200
1
curl -X GET "http://localhost:8080/auth/authorize"
<!doctype html><html lang="en">...</html>
POST /auth/authorize
Submit hosted authentication screen form
Accepts the hosted authentication form submission, detects the provider, and either renders the next step or redirects to the provider OAuth consent page.
Parameters
This endpoint does not accept parameters.
Request body
Required • application/json
Form payload submitted by the hosted authentication screen when a user selects a provider.
Form payload submitted by the hosted authentication screen when a user selects a provider.
| Field | Type | Description | Values |
email Optional | string (email) | Email address supplied by the end user for provider detection. | |
session Required | string | Single-use authorization code issued by Riposte. min length 1 | Example authsess_01HZY7FN5MSV2S8A1G31RZK8H4 |
state Required | string | Opaque state generated when the session was created. Used for CSRF protection. min length 1 | Example state_1234 |
Returns
Rendered HTML response for the hosted authentication experience.
Content type: application/json
Status: 200
1
curl -X POST "http://localhost:8080/auth/authorize" \
2
-H "Content-Type: application/json"
<!doctype html><html lang="en">...</html>
POST /auth/authorize/imap
Submit IMAP credentials for hosted authentication
Accepts IMAP credential submissions from the hosted authentication screen for custom providers.
Parameters
This endpoint does not accept parameters.
Request body
Required • application/json
Form payload submitted by the hosted authentication screen when configuring an IMAP mailbox with manual credentials.
Form payload submitted by the hosted authentication screen when configuring an IMAP mailbox with manual credentials.
| Field | Type | Description | Values |
allowSelfSigned Optional | string | When set to "true", disables strict TLS certificate validation. | — |
email Required | string (email) | Mailbox email address supplied by the end user. | — |
host Required | string | Hostname or IP address of the IMAP server. min length 1 | — |
mailbox Optional | string | Mailbox folder to synchronize (defaults to INBOX). | — |
password Required | string | IMAP password used to authenticate with the mail server. min length 1 | — |
port Optional | — | Port used to connect to the IMAP server (defaults to 993). | — |
secure Optional | string | When set to "true", indicates TLS/SSL should be used for the IMAP connection. | — |
session Required | string | Single-use authorization code issued by Riposte. min length 1 | — |
state Required | string | Opaque state generated when the session was created. Used for CSRF protection. min length 1 | — |
username Required | string | IMAP username used to authenticate with the mail server. min length 1 | — |
Returns
Rendered HTML response for the hosted authentication experience.
Content type: application/json
Status: 200
1
curl -X POST "http://localhost:8080/auth/authorize/imap" \
2
-H "Content-Type: application/json"
<!doctype html><html lang="en">...</html>
POST /auth/authorize/imap/folders
Validate IMAP credentials and list available mailboxes
Performs a lightweight connection test against the IMAP server and returns selectable mailboxes before completing authentication.
Parameters
This endpoint does not accept parameters.
Request body
Required • application/json
| Field | Type | Description | Values |
allowSelfSigned Optional | boolean | — | — |
email Optional | string | — | — |
host Required | string | — | — |
password Required | string | — | — |
port Optional | — | — | — |
secure Optional | boolean | — | — |
session Required | string | — | — |
state Required | string | — | — |
username Required | string | — | — |
Returns
Default Response
Content type: application/json
Status: 200
1
curl -X POST "http://localhost:8080/auth/authorize/imap/folders" \
2
-H "Content-Type: application/json"
No example response available.
POST /auth/sessions
Create single-use OAuth session
Generate a single-use authorization session that stores the desired redirect URI. The returned URL can be shared with end users to complete authentication.
Parameters
This endpoint does not accept parameters.
Request body
Optional • application/json
Defines metadata for a single-use authentication session. When the provider is omitted the built-in Riposte authentication screen will determine the best integration automatically.
Defines metadata for a single-use authentication session. When the provider is omitted the built-in Riposte authentication screen will determine the best integration automatically.
| Field | Type | Description | Values |
customUserId Optional | string | Optional application user identifier persisted alongside the account. | Example user_123 |
email Optional | string (email) | Optional email address hint passed to the authentication screen. | |
expiresInMinutes Optional | number | Override the default session expiry (in minutes). ≥ 1 • ≤ 1440 | Example 30 |
forceConsent Optional | boolean | When true the provider forces the OAuth consent screen even if the user has already granted access. | Example false |
provider Optional | string | Optional provider hint. When omitted, the authentication screen will prompt the user for their email address and persist the resolved provider once OAuth completes. gmailmicrosoftimap | Example gmail |
redirectUri Optional | string (uri) | App redirect URL. This is the user-facing URL Riposte should send the browser to after completing OAuth. Provide this value or configure riposte.app.redirectUrl so Riposte knows where to return the browser. | Example https://app.example.com/auth/callback |
Returns
Response containing the generated authorization URL and session metadata.
Content type: application/json
Status: 200
1
curl -X POST "http://localhost:8080/auth/sessions" \
2
-H "Content-Type: application/json" \
3
--data @- <<'BODY'
4
{
5
"redirectUri": "https://app.example.com/auth/callback",
6
"customUserId": "user_123",
7
"email": "[email protected]",
8
"expiresInMinutes": 30,
9
"forceConsent": false
10
}
11
BODY
{
"code": "authsess_01HZY7FN5MSV2S8A1G31RZK8H4",
"authUrl": "https://mail.example.com/auth/authorize?session=authsess_01HZY7FN5MSV2S8A1G31RZK8H4",
"expiresAt": "2024-06-12T18:43:21.000Z",
"provider": "gmail",
"email": "[email protected]"
}
POST /auth/sessions/{code}/start
Generate provider authorization URL for a session
Used by the built-in Riposte authentication screen to exchange a session code and state for a provider specific authorization URL.
Parameters
In path • Required
Single-use authorization code issued by Riposte
Request body
Required • application/json
Payload used by the built-in Riposte authentication screen to begin a provider specific OAuth flow on behalf of a session.
Payload used by the built-in Riposte authentication screen to begin a provider specific OAuth flow on behalf of a session.
| Field | Type | Description | Values |
email Optional | string (email) | Email address supplied by the end user for provider detection. | — |
provider Required | string | Provider selected by the authentication screen for this session. gmailmicrosoftimap | — |
state Required | string | Opaque state generated when the session was created. Used for CSRF protection. | — |
Returns
Default Response
Content type: application/json
Status: 200
1
curl -X POST "http://localhost:8080/auth/sessions/{code}/start" \
2
-H "Content-Type: application/json"
No example response available.
GET /providers/{providerName}/callback
OAuth callback handler
Handles OAuth callbacks from email providers (Gmail, Microsoft, etc.) and redirects users after successful authentication. This endpoint is public and called directly by OAuth providers.
Parameters
In query • Required
Authorization code from OAuth provider
In path • Required
The email provider name
Returns
Redirects to configured URL after successful authentication or error page on failure
Content type: application/json
Status: 302
1
curl -X GET "http://localhost:8080/providers/{providerName}/callback"
No example response available.
