OIDC and OAuth 2.0

Download OpenAPI specification:Download

OpenID Connect (OIDC) extends the authentication and authorization mechanisms of OAuth 2.0 with identity-focused security features like ID tokens and user profiles. Mosaic supports an OIDC-based integration option for hosted login using secure FIDO2 WebAuthn biometrics, and social providers like Google, Facebook, Apple, and LINE.

Decoupled authentication flows are supported using Client-Initiated Backchannel Authentication (CIBA) or using the OAuth Device Flow for input-limited devices.

Authorization

Start an authentication process. If the process is successful, an authorization code is returned to the redirect URI specified in the request. (See OIDC spec). For pushed authorization requests (PAR), provide request_uri returned by the PAR endpoint instead of authorization parameters.

Request
query Parameters
client_id
required
string

Client ID for which authentication is requested. For pushed authorization requests (PAR), the client ID should match the ID of the client that initiated the PAR flow.

redirect_uri
string

Required for authorization code flow. URI to redirect to upon completion of the authentication flow. This is the server GET endpoint used to call the token endpoint, and should accept code as a query parameter. This URI must also be configured as an allowed redirect URI in the Mosaic Admin Portal

scope
string

Required for authorization code flow. Scope of the requested access. Used to request specific user details like email. Must include openid and can include additional values (space delimited). offline_access scope allows refreshing access tokens.

Enum: "openid" "email" "phone" "offline_access"
loginType
string
Deprecated

For authorization code flow. Authentication method to be used for this process, where centralized is used to request authentication via the Authentication Hub.

Enum: "google-direct" "apple-direct" "facebook-direct" "webauthn-direct" "line-direct" "centralized"
response_type
string
Default: "code"

Required for authorization code flow. Response type requested for the authentication flow.

Value: "code"
prompt
string

For authorization code flow. Space-delimited, case-sensitive list of string values that specifies whether the Authorization Server prompts the end-user for reauthentication and consent.

Enum: Description
login

Prompts the user to authenticate.

consent

Prompts the user for consent if required. Must be passed to receive a refresh token and when trying to perform silent authentication to the app you haven't logged in before.

none

Checks for an existing session (and consent if required). Used for silent authentication to the same app as initially logged in to.

nonce
string

For authorization code flow. A random value that is included in the authentication request from the client (e.g. browser) to mitigate replay attacks. It will be added to the id_token and the backend service should only accept id_tokens that include the same nonce value as the one included in the original request.

state
string

For authorization code flow. An opaque string that is used to maintain state between the request and the callback. It will be added to the redirect URI as a query parameter, which should be validated by your server to protect against cross-site request forgery (CSRF) attacks

code_challenge
string

Required for authorization code flow with PKCE. A hashed value of the 'code_verifier' required for PKCE

code_challenge_method
string

Required for authorization code flow with PKCE. The hashing mechanism used to transform a code_verifier into the code_challenge in PKCE flows, must be 'S256'

resource
string

For authorization code flow. Resource URI the authentication request is attempting to access, which is reflected in the audience (aud claim) of the access token. This must be configured as resource for the application.

claims
string

For authorization code flow. A stringified object used to request additional claims in the ID token, such as roles, permissions, and other user profile data. The structure is per the OIDC Standard. For supported claims and how to request custom claims, see the ID Token Reference. Note: You should stringify the value.

Example: claims={"id_token":{"roles":null}}
acr_values
string

For authorization code flow. Requested ACR values, specified as a space-separated string. The acr claim of the resulting ID token will indicate which requirements were satisfied.

Enum: Description
mfa

Requires multi-factor authentication. If it isn't satisfied, an error is returned indicating how to satisfy it via email/SMS authentication.

phone_number

Requires a verified phone number for a WebAuthn login. If it isn't yet verified, an SMS verification process will occur.

urn:transmit:google_direct

Requires Google authentication method to be used for this process.

urn:transmit:apple_direct

Requires Apple authentication method to be used for this process.

urn:transmit:facebook_direct

Requires Facebook authentication method to be used for this process.

urn:transmit:webauthn_direct

Requires WebAuthn authentication method to be used for this process.

urn:transmit:line_direct

Requires Line authentication method to be used for this process.

urn:transmit:centralized

Requires centralized authentication method to be used for this process, centralized is used to request authentication via the Authentication Hub.

createNewUser
boolean
Default: false

For authorization code flow. Indicates if a new user should be created if one doesn't already exist (or associated with the app if the user isn't already). Public sign up must be enabled for this application.

login_hint
string

For authorization code flow. Hint for the user's login identifier for WebAuthn login.

Example: login_hint=user@acme.com
custom_message
string

For authorization code flow. Custom message to present on the consent screens for WebAuthn login, which provides authentication context details.

Example: custom_message=Welcome to Acme
ui_locales
string

For authorization code flow. Preferred languages for the user interface for WebAuthn login, specified as a space-separated list of language tag values [RFC5646], ordered by preference.

org_id
string

For authorization code flow. Organization ID, used for member login in B2B scenarios

request_uri
string

Required for PAR flow. The URI returned by the PAR request. The request_uri value is bound to the client that sent the PAR authorization request.

Responses
303

Redirects with authentication result.

400
500
get/oidc/auth
Request samples 
Response samples 
application/json
{
  • "message": "Bad request",
  • "error_code": 400
}
Backchannel authentication
Start a backchannel authentication process (See CIBA spec). The request can either be used to obtain a direct link (for example, to embed in a QR code) or to send the user a link by SMS or email. When opened, this link will initiate an authentication process. The request returns the authentication request ID that will be used to complete the process on the authenticating device (by calling /auth/backchannel/complete) and obtain the token. If the link channel was specified, the response will also include the link.


Request 
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string
Client ID for which authentication is requested.


 
client_secret
required
string
Client secret.


 
scope
required
string
Scope of the requested access. Used to request specific user details like email. Must include openid and can include additional values (space delimited). offline_access scope allows refreshing access tokens.


 Enum: "openid" "email" "phone" "offline_access"  
login_hint
required
string
Identifier of a user for whom authentication is requested (email, phone or user_id)


 
binding_message
string^[a-zA-Z0-9-._+/!?#]{1,20}$
A message intended to be displayed on both consumption and authentication devices so the end-user can see how they are interconnected for the transaction.


 The message needs to be 1 - 20 characters in length and should contain only digits, alphabet and the characters: -._+/!?#


 
requested_expiry
integer
 Default:  600
Requested expiration of the authentication request in seconds.


 
request_context
string
A stringify object that contains more data about the request


 example of object: 


{
    "channel": "email", 
    "login_hint_type": "email", 
    "custom_message": "click on the following link to approve the access: "
}



Note: You should stringify the value. 






property
description





channel
The channel to use for triggering the authentication device, one of the values: sms (default), email, link




login_hint_type
The login_hint identifier type, one of the values: phone (default), email, user_id




custom_message
Custom message to be sent when triggering the authentication device (default: To verify it's you, click this link:)





 
Responses 
200
The authentication request has been accepted


400
500
post/oidc/backchannel
Request samples 
application/x-www-form-urlencoded
client_id=string&client_secret=string&scope=openid&login_hint=string&binding_message=string&requested_expiry=600&request_context=%7B%22channel%22%3A%20%22email%22%2C%20%22login_hint_type%22%3A%20%22email%22%2C%20%22custom_message%22%3A%20%22click%20on%20the%20following%20link%20to%20approve%20the%20access%3A%20%22%7D
Response samples 
application/json
{
  • "auth_req_id": "string",
  • "expires_in": 600
}
Device authorization
Initiate the device flow (See OAuth 2.0 Device Authorization Grant (RFC 8628)). This call returns a user code and verification URI for the user to approve or deny access on a separate device. Additionally, a device code is provided to obtain the token.


Request 
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string
Client ID for which authentication is requested.


 
client_secret
required
string
Client secret.


 
scope
required
string
Scope of the requested access. Used to request specific user details like email. Must include openid and can include additional values (space delimited). offline_access scope allows refreshing access tokens.


 Enum: "openid" "email" "phone" "offline_access"  
loginType
string
 Deprecated 
Authentication method to be used for this process, where centralized is used to request authentication via the Authentication Hub.


 Enum: "google-direct" "apple-direct" "facebook-direct" "webauthn-direct" "line-direct" "centralized"  
acr_values
required
string
Requested ACR values, specified as a space-separated string. The acr claim of the resulting ID token will indicate which requirements were satisfied.


 Enum: Description
urn:transmit:google_direct
Requires Google authentication method to be used for this process.


urn:transmit:apple_direct
Requires Apple authentication method to be used for this process.


urn:transmit:facebook_direct
Requires Facebook authentication method to be used for this process.


urn:transmit:webauthn_direct
Requires WebAuthn authentication method to be used for this process.


urn:transmit:line_direct
Requires Line authentication method to be used for this process.


urn:transmit:centralized
Requires centralized authentication method to be used for this process, centralized is used to request authentication via the Authentication Hub.


 
Responses 
200
The authorization request has been accepted


400
500
post/oidc/device/auth
Request samples 
application/x-www-form-urlencoded
client_id=string&client_secret=string&scope=openid&loginType=google-direct&acr_values=urn%3Atransmit%3Agoogle_direct
Response samples 
application/json
{
  • "device_code": "string",
  • "user_code": "string",
  • "verification_uri": "string",
  • "verification_uri_complete": "string",
  • "expires_in": 600
}
Token
Retrieves tokens in various OIDC/OAuth flows. It's used to retrieve an ID token and user access token upon successful user authentication (for an authorization code flow), or to retrieve client access tokens for API authorization (in a client credentials flow).


Request 
Request Body schema: application/x-www-form-urlencoded
required
One of:
client_id
required
string
Client ID for which authentication is requested.


 
client_secret
required
string
Client secret.


 
code
required
string
Authorization code received from a successful authentication flow.


 
grant_type
required
string
Should be set to authorization_code to identify users upon successful authentication.


 Value: "authorization_code"  
redirect_uri
required
string
Redirect URI passed in the authorization request.


 
Responses 
200
Returns user tokens


400
500
post/oidc/token
Request samples 
application/x-www-form-urlencoded
client_id=string&client_secret=string&code=string&grant_type=authorization_code&redirect_uri=string
Response samples 
application/json
{
  • "access_token": "string",
  • "id_token": "string",
  • "expires_in": 3600,
  • "scope": "string",
  • "token_type": "string",
  • "refresh_token": "string"
}
Revocation
Revoke a specific refresh token, making it no longer valid and forcing the user to re-authenticate if they need a new one.


Request 
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string
Client ID.


 
client_secret
required
string
Client secret.


 
token
required
string
Token to revoke.


 
token_type_hint
string
A hint about the type of the token submitted for revocation.


 Enum: "access_token" "refresh_token"  
Responses 
200
Token revoked successfully


400
500
post/oidc/token/revocation
Request samples 
application/x-www-form-urlencoded
client_id=string&client_secret=string&token=string&token_type_hint=access_token
Response samples 
application/json
{
  • "message": "Bad request",
  • "error_code": 400
}
Logout
Logs out the user by terminating all their sessions for this tenant. See OIDC RP-Initiated Logout


Request 
query Parameters
client_id
string
Recommended. Client ID initiating the logout request. If not passed, our default logout success page will be shown instead.


 
id_token_hint
string
Previously issued ID Token passed as a hint about the user's current authenticated session with the client.


 
post_logout_redirect_uri
string
Recommended. URI to which the user should be redirected after the logout has been performed. If not passed, our default logout success page will be shown instead.


 
state
string
Opaque value used to maintain state between the logout request and the post logout redirect URI (which will receive it via the state query parameter).


 
Responses 
200
Returns HTML that when parsed by the browser, will finish the logout flow.


400
500
get/oidc/session/end
Request samples 
Response samples 
application/json
{
  • "message": "Bad request",
  • "error_code": 400
}
JWKS
Returns the signing key used to validate the signature of the authorization request (per OIDC spec)


Responses 
200
500
get/oidc/jwks
Request samples 
Response samples 
application/json
{
  • "keys": [
    ]
}
Discovery
Get all metadata for the OIDC server, including paths to relevant endpoints. (see OIDC spec)


Responses 
200
500
get/oidc/.well-known/openid-configuration
Request samples 
Response samples 
application/json
{
  • "message": "Something went wrong - Internal server error",
  • "error_code": 500
}
PAR
Pushed authorization request (PAR) is a secure way to initiate the authorization flow. All parameters are sent in the body of the request (see OAuth 2.0 Pushed Authorization Requests RFC).


Request 
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string
Client ID for which authentication is requested.


 
client_secret
required
string
Client secret.


 
redirect_uri
required
string
URI to redirect to upon completion of the authentication flow. This is the server GET endpoint used to call the token endpoint, and should accept code as a query parameter. This URI must also be configured as an allowed redirect URI in the Admin Portal


 
response_type
required
string
Response type requested for the authentication flow.


 Value: "code"  
scope
string
Scope of the requested access. Used to request specific user details like email. Must include openid and can include additional values (space delimited). offline_access scope allows refreshing access tokens.


 Enum: "openid" "email" "phone" "offline_access"  
prompt
string
Space-delimited, case-sensitive list of string values that specifies whether the Authorization Server prompts the end-user for reauthentication and consent.


 Enum: "none" "login" "consent"  
nonce
string
A random value that is included in the authentication request from the client (e.g. browser) to mitigate replay attacks. It will be added to the id_token and the backend service should only accept id_tokens that include the same nonce value as the one included in the original request.


 
state
string
An opaque string that is used to maintain state between the request and the callback. It will be added to the redirect URI as a query parameter, which should be validated by your server to protect against cross-site request forgery (CSRF) attacks


 
resource
string
Resource URI the authentication request is attempting to access, which is reflected in the audience (aud claim) of the access token. This must be configured as resource for the application.


 
claims
string
A stringified object used to request additional claims in the ID token, such as roles, permissions, and other user profile data.
The structure is per the OIDC Standard. For supported claims and how to request custom claims, see the ID Token Reference.
Note: You should stringify the value.


 
acr_values
string
Requested ACR values, specified as a space-separated string. The acr claim of the resulting ID token will indicate which requirements were satisfied.


 Enum: "mfa" "phone_number" "urn:transmit:google_direct" "urn:transmit:apple_direct" "urn:transmit:facebook_direct" "urn:transmit:webauthn_direct" "urn:transmit:line_direct" "urn:transmit:centralized"  
createNewUser
boolean
 Default:  false
Indicates if a new user should be created if one doesn't already exist (or associated with the app if the user isn't already). Public sign up must be enabled for this application.


 
login_hint
string
Hint for the user's login identifier for WebAuthn login.


 
custom_message
string
Custom message to present on the consent screens for WebAuthn login, which provides authentication context details.


 
ui_locales
string
Preferred languages for the user interface for WebAuthn login, specified as a space-separated list of language tag values [RFC5646], ordered by preference.


 
org_id
string
Organization ID, used for member login in B2B scenarios


 
code_challenge
string
A hashed value of the 'code_verifier' required for PKCE


 
code_challenge_method
string
The hashing mechanism used to transform a code_verifier into the code_challenge in PKCE flows, must be 'S256'


 
Responses 
200
The request has been accepted


400
500
post/oidc/request
Request samples 
application/x-www-form-urlencoded
client_id=string&client_secret=string&redirect_uri=string&response_type=code&scope=openid&prompt=none&nonce=string&state=string&resource=string&claims=string&acr_values=mfa&createNewUser=false&login_hint=string&custom_message=Welcome%20to%20Acme&ui_locales=string&org_id=string&code_challenge=string&code_challenge_method=string
Response samples 
application/json
{
  • "request_uri": "string",
  • "expires_in": 60
}