Back-Channel Login

The Back-Channel Login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for push notifications using the Guardian SDK.

Use the Back-Channel Login endpoint to authenticate users for the following use cases:

• Users are not in front of the application that requires authentication, such as when they’re telephoning a call center.
• The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations (e.g., web browser for financial transactions).
• The consumption device has limited interactive capability (e.g., e-bicycles or e-scooters).

Response Body

If the request is successful, you should receive a response like the following:

{
  "auth_req_id": "eyJh...",
  "expires_in": 300,
  "interval": 5
}

The auth_req_id value should be kept as it is used later in the flow to identify the authentication request.

The expires_in value tells you how many seconds you have until the authentication request expires.

The interval value tells you how many seconds you must wait between poll requests.

The request should be approved or rejected on the user’s authentication device using the Guardian SDK.

Remarks

• The login_hint value follows the iss_sub format. For example:

{ "format": "iss_sub", "iss": "https://[TENANT_DOMAIN]/", "sub": "auth0|[USER ID]" }

• Authentication can use Client Secret (via HTTP Basic Auth or Post), Private Key JWT, or mTLS. Please refer to the detailed examples above.

POST https://{yourDomain}/bc-authorize

Back-Channel Login

cURL

curl --request POST \
  --url https://{yourDomain}/bc-authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=<string>' \
  --data 'binding_message=<string>' \
  --data 'login_hint=<string>' \
  --data scope=openid \
  --data 'audience=<string>' \
  --data resource=https://api.example.com/ \
  --data requested_expiry=300 \
  --data 'authorization_details=<array>'

200

{
  "auth_req_id": "eyJh...",
  "expires_in": 300,
  "interval": 5
}

Authorizations

Authorization · string · header · required

Access token obtained from the authentication flow

Body

application/x-www-form-urlencoded

client_id · string · required

The client_id of your application.

binding_message · string · required

A human-readable string for the user to ensure they approve the correct request.

login_hint · string · required

A JSON object containing user details for authentication in the iss_sub format.

scope · string · required

Space-separated list of OIDC and custom API scopes, including openid at a minimum.

Example:

"openid"

audience · string

Optional unique identifier of the target API for access tokens.

resource · string

The identifier of the target API (resource server) you want to access. Must match an API Identifier registered in your Auth0 tenant. Used as an alternative to audience when the tenant's Resource Parameter Compatibility Profile is set to compatibility.

Example:

"https://api.example.com/"

requested_expiry · string

Custom expiry time for the request in seconds (1-300). Defaults to 300 seconds.

Example:

300

authorization_details · array

An optional JSON array of objects that describe the permissions to be authorized. Each object’s type value should be previously registered on the resource server using the Resource Server’s authorization_details parameter. To learn more, read the Update a resource server Management API documentation.

Response

200

application/json

Authentication request successfully initiated.