Requesting Authorization Code on the Web

📘

This section and its subsections are handled by the iOS or Android SDK within your application on a user's primary device.

When you request an authorization code, the request will be to the carrier's AUTHORIZATION_ENDPOINT returned in the discovery response. The REDIRECT_URI created when you retrieved your CLIENT_ID and CLIENT_SECRET in the ZenKey Developer Portal are also included as well as several other parameters listed below. Note that LOGIN_HINT_TOKEN is optional and should only be included when present in the discovery response.

https://AUTHORIZATION_URL?
    client_id=CLIENT_ID
    &login_hint_token=LOGIN_HINT_TOKEN
    &redirect_uri=REDIRECT_URI
    &response_type=code
    &scope=SCOPES
    &state=STATE

Parameter

Description

AUTHORIZATION_URL

The carrier's authorization endpoint from the OpenID configuration document.

CLIENT_ID

Obtained in the ZenKey developer portal.

LOGIN_HINT_TOKEN

The LOGIN_HINT_TOKEN from the carrier Discovery UI response. This optional parameter returns if the request is made by a secondary device such as a desktop or tablet. Requests originating on primary devices will not return this parameter. Only include LOGIN_HINT_TOKEN if present in the discovery response. Do not include LOGIN_HINT_TOKEN if the parameter is not present in the response.

REDIRECT_URI

ZenKey redirects users back to this URL in your app. It contains an authorization CODE that your app can exchange for a token. It must match the value specified during registration in SP portal.

STATE

Token generated earlier.

SCOPES

User attributes like name, email, phone, and address.

ACR_VALUES

(Optional) The user authentication level to request from users.

a1: For use when requiring only a low-level authentication. Users are not asked to provide their PIN or biometric data.

a2: Do not use this authentication level; it produces inconsistent effects between carriers.

a3: (Default) Use this authentication level if you require users to provide their PIN or biometric data. In this experience, users must provide their PIN or biometric data if they have not authenticated in the last 30 minutes.

The Authorization Response

The user-agent redirects to the specified REDIRECT_URI with these URL parameters.

Parameter

Description

CODE

Used in the token request.

STATE

Validate value against the token generated earlier.

MCCMNC

Needed for SP client to inform SP server of carrier.

CORRELATION_ID

Tracking ID used for transaction logging. Defined by SP issuing the request. SP must use the service portal to access log entries.

ERROR

Tracking ID used for transaction logging. Defined by SP issuing request. SP must use Service Portal to access log entries.

ERROR_DESCRIPTION

Human-readable ASCII encoded text description of the error. For instance: “User is on a carrier not yet integrated with ZenKey”. For more info, refer to OIDC specs.


Did this page help you?