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) and handles the redirect back to
/providers/{providerName}/callback.
- Riposte redirects the user to the
redirectUri you supplied in the session payload so your product can confirm success.
- Your product brings the user back into your app.
If Google or Microsoft sends users directly back to your product instead of Riposte, double-check the authorized redirect URIs
in the provider console. The admin portal’s guided Google setup walks through these URLs step by step and flags swaps between
the provider redirect and your product redirect 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/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
Required • application/json
Defines the redirect target for a single-use authentication session. When the provider is omitted the built-in Riposte authentication screen will determine the best integration automatically.
Defines the redirect target 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 Required | string (uri) | URL users will be redirected to after completing the OAuth flow. | 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
Additional parameters
Optional state parameter for CSRF protection
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.
