# Authorize The Authorization Endpoint is a [standard endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) that triggers a BankID authentication of an end-user via one of the [Identity Providers](https://docs.stoe.no/bankid-oidc-provider/core-concepts/identity-providers.md), following the [authorization code flow](https://docs.stoe.no/bankid-oidc-provider/flows.md). > **Use OpenID Configuration** > > You will always find the up-to-date URL for the Authorization Endpoint in the [OpenID Configuration](https://docs.stoe.no/bankid-oidc-provider/api/openid-configuration.md) > > - as `authorization_endpoint`. ## API ### Request ```http GET [authorization_endpoint] ?client_id=myclient-bankid-current &scope=openid+profile &acr_values=urn:bankid:bid &redirect_uri=https%3A%2F%2Fmywebapp.example.org%2Fcallback &response_type=code &state=01e3ac8e-4a26-4dfb-79ca-2631394c4144 &nonce=1fb72f68-1bea-2ba2-12d7-24df1c999d1b &code_challenge=rMU4NcLC3_O_tsTZ3gQE1ONoXD6OMZph_2zRuobajhQ &code_challenge_method=S256 ``` #### Query Parameters | Name | Description | | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | client_id | Unique ID (arbitrary string) for the OIDC Client in question. This is created as part of the provisioning process. | | redirect_uri | Redirect URI to which the Authorize response will be sent. This URI must exactly match one of the Redirect URI values for the OIDC Client pre-registered at the OpenID Provider. | | scope | List of scope values specifying what kind of resources (dataset) the OIDC Client requests access to. The value openid must always be included in the list. Each scope value must be separated by space. Scope values are case-sensitive. | | response_type | Determines the message flow to be used, thus also governing the content and type of the response from the Authorize endpoint. Only `code` (Authorization code flow) is supported. | | response_mode | The response mode to be used for returning parameters from the Authorization Endpoint via redirect_uri. The following values are supported: `query`, `fragment`, `form_post`. | | acr_values | Allows you to determine the a Level of Assurance (LoA) and ACR (_Authentication Context Class Reference_) value by selecting the [Identity provider](https://docs.stoe.no/bankid-oidc-provider/core-concepts/identity-providers.md) (IDP) used for authentication. The value is a space-separated list of ACR values, and we support the following values: - `urn:bankid:bis` - Biometric authentication using WebAuthn at LoA 3. - `urn:bankid:bid` - Authentication using BankID at LoA 4. If none of these parameters are set, the default LoA is 4 (BankID High). **Note**: This parameter has no effect if the `login_hint` parameter contains a reference to any particular IDP. Nor does it have any effect if the `id_token_hint` parameter is set. | | login_hint ([request objects/PAR](https://docs.stoe.no/bankid-oidc-provider/core-concepts/login-hint.md) only) | This parameter can be used to prefill the user ID in the login form. The value is a colon (:) followed by NNIN (Norwegian National Identity Number). Example: `:01010112345` **Do not send login_hint as query parameter.** Use [PAR or encrypted request objects](https://docs.stoe.no/bankid-oidc-provider/core-concepts/login-hint.md). **Note**: Previously, `login_hint` was used to select IDP or LoA; you should instead use the `acr_values` parameter for that purpose. **Warning**: Specifying nnin in an unencrypted query param login_hint is not supported in [API Version 4](https://docs.stoe.no/bankid-oidc-provider/api-versions.md). | | code_challenge | Base64-URL-encoded string of the SHA256 hash of a "code verifier" value generated on merchant side. A code verifier is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -.\_\~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long. | | code_challenge_method | Method used to encode the code verifier. Only "S256" (SHA256) is supported. | | state | Opaque value used to maintain state between the request and the callback. It is strongly recommended that merchants provide this value to mitigate Cross-Site Request Forgery. | | nonce | String value used to associate a ODIC Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the resulting ID Token as `nonce` claim. | | api_version | The version of the API of the BankID OpenID Provider to be used. Integer value. See [API versions](https://docs.stoe.no/bankid-oidc-provider/api-versions.md) for more information. | | ui_locales | May be used to set a language preference for GUI handling. The default GUI experience supports: `nb` (Norsk Bokmål), `nn` (Norsk Nynorsk) and 'en' (English). If ui_locales is not set, the first (if any) `Accept-Language` header of the request is used to determine preferred locale. Otherwise `nb` is used by default. | | prompt | Support for the standardized values `none` and `login`. The former can be used to check for an existing (still valid) authentication session with the OIDC provider. The latter can be used to force a re-authentication, possibly with a different `login_hint` and/or `acr_values`. Optional. | | display | The display parameter allows Clients to adjust the user interface displayed to end-users to make it more consistent with the device type and viewport size. We support: `page` (default) - standard responsive view (desktops, tablets). `touch` - suitable for integration in mobile apps. `wap` - same as `touch` above. `popup` - suitable for popup or iframe integrations. | | request | This parameter may be used to group and send several query parameters as one. The [standard](https://openid.net/specs/openid-connect-core-1_0.html#RequestObject) specifies guidelines on how to use it. BankID supports both plaintext and encrypted request objects. Encrypted and signed objects are in certain cases possible. If the request parameter contains personal information, it should be encrypted. See [encryption](https://docs.stoe.no/bankid-oidc-provider/core-concepts/encrypted-request-object.md). | | request_uri | Only supported when using with [Pushed Authorization Requests (PAR)](https://docs.stoe.no/bankid-oidc-provider/api/par.md) to reference previously pushed request parameters. | | authorization_details ([PAR](https://docs.stoe.no/bankid-oidc-provider/api/par.md) only) | URL-encoded JSON array containing a permission statement. Only accepted in PAR requests. Cannot be used together with `permission_token`. See [Authorization Details](https://docs.stoe.no/bankid-oidc-provider/advanced-topics/authorization-details.md) for more information. | | permission_token | Token received from the [Permissions API](https://docs.stoe.no/bankid-with-biometrics/apis/permissions-api.md) after registering a permission. Cannot be used together with `authorization_details`. | | id_token_hint | JWT value for an ID Token previously issued by the OIDC Provider used as a hint about the end user's existing session with the OIDC provider. Note that this parameter has precedence before both `acr_values` and `login_hint`, but precedence after the `prompt` parameter. If the ID Token has expired, a new authentication is triggered for the IDP option that was used when the ID Token was first issued. Otherwise, the authentication is still valid and the OIDC Provider proceeds directly to [consent handling](https://docs.stoe.no/bankid-oidc-provider/core-concepts/consent-handling.md). | #### Encrypted request object Instead of sending plain text query parameters you can send an encrypted request object. This will allow you to prefill **sensitive data** such as NNIN. Read more [here](https://docs.stoe.no/bankid-oidc-provider/core-concepts/encrypted-request-object.md). ### Response After a series of redirects that will eventually lead back to the `redirect_uri` specified in the request, the response is delivered in the method specified by the `response_mode` parameter in the request. Typically, as a query parameter in the URL: ``` [your_web_app]/callback ?state=01e3ac8e-4a26-4dfb-79ca-2631394c4144b &session_state=12801cef-7746-4dd6-a418-43bda5c7002a &code=aa47ea38-633d-4e9a-bd41-4f1a5b50fe7c.66801cef-7746-4dd6-4391-43bda5c7002b.0ab47fe7-0376-4b80-b217-065f5a5a3760 ``` | Name | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **On success** | | | state | The state parameter should be used by the merchant to correlate the initial request and the callback response. It will only be included if provided in the initial request. | | code | A short-lived, one time use code that is used to retrieve the ID, Access and Refresh tokens using the [token endpoint](https://docs.stoe.no/bankid-oidc-provider/api/token.md). | | **On error** | | | state | The state parameter should be used by the merchant to correlate the initial request and the callback response. It will only be included if provided in the initial request. | | error | The error code if the authentication was unsuccessful. | | error_description | A human-readable description of the error. |