Backchannel authentication

Authorization

Request

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.

Query

client_idstringrequired

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_uristring

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

scopestring

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"

response_typestring

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

Default "code"

Value"code"

promptstring

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 Value	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.

noncestring

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.

statestring

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_challengestring

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

code_challenge_methodstring

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'

resourcestring

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.

claimsstring

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_valuesstring

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 Value	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: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.

createNewUserboolean

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.

Default false

login_hintstring

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

Example: login_hint=user@acme.com

custom_messagestring

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_localesstring

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_idstring

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

request_uristring

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.

loginTypestringDeprecated

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"

curl -i -X GET \
  'https://api.transmitsecurity.io/cis/oidc/auth?client_id=string&redirect_uri=string&scope=openid&response_type=code&prompt=login&nonce=string&state=string&code_challenge=string&code_challenge_method=string&resource=string&claims={%22id_token%22%3A{%22roles%22%3Anull}}&acr_values=mfa&createNewUser=false&login_hint=user%40acme.com&custom_message=Welcome+to+Acme&ui_locales=string&org_id=string&request_uri=string&loginType=google-direct'

Responses

Redirects with authentication result.

Response

No content

Backchannel authentication

Request

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.

Bodyapplication/x-www-form-urlencodedrequired

client_idstringrequired

Client ID for which authentication is requested.

client_secretstringrequired

Client secret.

scopestringrequired

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_hintstringrequired

Identifier of a user for whom authentication is requested (email, phone or user_id)

binding_messagestring^[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_expiryinteger

Requested expiration of the authentication request in seconds.

Default 600

request_contextstring

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:`)

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

curl -i -X POST \
  https://api.transmitsecurity.io/cis/oidc/backchannel \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d client_id=string \
  -d client_secret=string \
  -d scope=openid \
  -d login_hint=string \
  -d binding_message=string \
  -d requested_expiry=600 \
  -d 'request_context={"channel": "email", "login_hint_type": "email", "custom_message": "click on the following link to approve the access: "}'

Responses

The authentication request has been accepted

Bodyapplication/json

auth_req_idstringrequired

A unique identifier of the authentication request.

expires_inintegerrequired

A positive integer value indicating the expiration time of the auth_req_id in seconds since the authentication request was received

Default 600

Response

application/json

{
  "auth_req_id": "string",
  "expires_in": 600
}

Device authorization

Request

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.

Bodyapplication/x-www-form-urlencodedrequired

client_idstringrequired

Client ID for which authentication is requested.

client_secretstringrequired

Client secret.

scopestringrequired

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"

acr_valuesstringrequired

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

Enum Value	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: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.

loginTypestringDeprecated

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"

curl -i -X POST \
  https://api.transmitsecurity.io/cis/oidc/device/auth \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d client_id=string \
  -d client_secret=string \
  -d scope=openid \
  -d loginType=google-direct \
  -d acr_values=urn:transmit:google_direct

Responses

The authorization request has been accepted

Bodyapplication/json

device_codestringrequired

The device code to be used to obtain a token.

user_codestringrequired

The user code to be displayed to the user.

verification_uristring

The URI that verifies the user submitted a valid user code on the input page.

verification_uri_completestring

(Recommended) The URI with embedded user code that verifies if the user code is valid while skipping the input page.

expires_inintegerrequired

The number of seconds before the device_code expires.

Default 600

Response

application/json

{
  "device_code": "string",
  "user_code": "string",
  "verification_uri": "string",
  "verification_uri_complete": "string",
  "expires_in": 600
}

Token

Request

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).

Bodyapplication/x-www-form-urlencodedrequired

One of:

client_idstringrequired

Client ID for which authentication is requested.

client_secretstringrequired

Client secret.

codestringrequired

Authorization code received from a successful authentication flow.

grant_typestringrequired

Should be set to authorization_code to identify users upon successful authentication.

Value"authorization_code"

redirect_uristringrequired

Redirect URI passed in the authorization request.

curl -i -X POST \
  https://api.transmitsecurity.io/cis/oidc/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d client_id=string \
  -d client_secret=string \
  -d code=string \
  -d grant_type=authorization_code \
  -d redirect_uri=string

Responses

Returns user tokens

Bodyapplication/json

One of:

access_tokenstringrequired

User access token for accessing endpoints on behalf of the authenticated user.

id_tokenstringrequired

ID token that identifies the user.

expires_innumberrequired

Expiration time of the access token in seconds.

Default 3600

scopestringrequired

Scope of the access token.

token_typestringrequired

Bearer.

refresh_tokenstring

Refresh token used to refresh an expired access token. Returned only if the requested prompt includes consent and scope includes offline_access.

Response

application/json

{
  "access_token": "string",
  "id_token": "string",
  "expires_in": 3600,
  "scope": "string",
  "token_type": "string",
  "refresh_token": "string"
}

Revocation

Request

Revoke a specific refresh token, making it no longer valid and forcing the user to re-authenticate if they need a new one.

Bodyapplication/x-www-form-urlencodedrequired

client_idstringrequired

Client ID.

client_secretstringrequired

Client secret.

tokenstringrequired

Token to revoke.

token_type_hintstring

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

Enum"access_token""refresh_token"

curl -i -X POST \
  https://api.transmitsecurity.io/cis/oidc/token/revocation \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d client_id=string \
  -d client_secret=string \
  -d token=string \
  -d token_type_hint=access_token

Responses

Token revoked successfully

Response

No content

Terminate sessions

Request

Terminates all the user’s active sessions for this tenant. Note that running this call does not revoke valid access tokens or refresh tokens. See OIDC RP-Initiated Logout

Query

client_idstring

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

id_token_hintstring

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

post_logout_redirect_uristring

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. This URI must be configured in the client’s allowed redirect URIs.

statestring

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).

curl -i -X GET \
  'https://api.transmitsecurity.io/cis/oidc/session/end?client_id=string&id_token_hint=string&post_logout_redirect_uri=string&state=string'

Responses

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

Bodytext/html

Response

No content

JWKS

Request

Returns the signing key used to validate the signature of the authorization request (per OIDC spec)

curl -i -X GET \
  https://api.transmitsecurity.io/cis/oidc/jwks

Responses

Bodyapplication/json

keysArray of objects

Response

application/json

{
  "keys": [
    { … }
  ]
}

Discovery

Request

Get all metadata for the OIDC server, including paths to relevant endpoints. (see OIDC spec)

curl -i -X GET \
  https://api.transmitsecurity.io/cis/oidc/.well-known/openid-configuration

Responses

Bodyapplication/json

Response

application/json

null

PAR

Request

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).

Bodyapplication/x-www-form-urlencodedrequired

client_idstringrequired

Client ID for which authentication is requested.

client_secretstringrequired

Client secret.

redirect_uristringrequired

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_typestringrequired

Response type requested for the authentication flow.

Value"code"

scopestring

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"

promptstring

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"

noncestring

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.

statestring

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

resourcestring

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.

claimsstring

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_valuesstring

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:line_direct""urn:transmit:centralized"

createNewUserboolean

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.

Default false

login_hintstring

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

custom_messagestring

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

Example: "Welcome to Acme"

ui_localesstring

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

org_idstring

Organization ID, used for member login in B2B scenarios

code_challengestring

A hashed value of the 'code_verifier' required for PKCE

code_challenge_methodstring

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

curl -i -X POST \
  https://api.transmitsecurity.io/cis/oidc/request \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d client_id=string \
  -d client_secret=string \
  -d redirect_uri=string \
  -d response_type=code \
  -d scope=openid \
  -d prompt=none \
  -d nonce=string \
  -d state=string \
  -d resource=string \
  -d claims=string \
  -d acr_values=mfa \
  -d createNewUser=false \
  -d login_hint=string \
  -d 'custom_message=Welcome to Acme' \
  -d ui_locales=string \
  -d org_id=string \
  -d code_challenge=string \
  -d code_challenge_method=string

Responses

The request has been accepted

Bodyapplication/json

request_uristringrequired

A single-use reference to the respective request data in the subsequent authorization request.

expires_inintegerrequired

A positive integer value indicating the expiration time of the request_uri in seconds since the request was received

Default 60

Response

application/json

{
  "request_uri": "string",
  "expires_in": 60
}

OIDC and OAuth 2.0

Authorization

Request

Responses

Backchannel authentication

Request

Responses

Device authorization

Request

Responses

Token

Request

Responses

Revocation

Request

Responses

Terminate sessions

Request

Responses

JWKS

Request

Responses

Discovery

Request

Responses

PAR

Request

Responses