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.