> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopae.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Authorization

> Initiates the OIDC Authorization Code flow with optional PKCE. Front‑channel redirect; no Authorization header.

Initiate user authentication by redirecting the browser to Hopae Connect's `/auth` endpoint.

## Query Parameters

<ParamField query="client_id" type="string" required>
  Your application's OIDC client identifier.
</ParamField>

<ParamField query="redirect_uri" type="string" required>
  Exact match to a pre‑registered redirect URI for your client.
</ParamField>

<ParamField query="response_type" type="string" required default="code">
  Must be `code`.
</ParamField>

<ParamField query="scope" type="string" required default="openid idv">
  Space‑delimited scopes. Must include `openid idv`. Supported: `openid`, `idv`.
</ParamField>

<ParamField query="code_challenge" type="string">
  PKCE code challenge (recommended for public clients).
</ParamField>

<ParamField query="code_challenge_method" type="string" default="S256">
  Must be `S256` when `code_challenge` is present.
</ParamField>

<ParamField query="nonce" type="string">
  Recommended to bind the ID Token to a client session.
</ParamField>

<ParamField query="acr_values" type="string">
  Request a minimum Level of Assurance. Format: `loa:{level}` where level is 1–5.
  See [Level of Assurance](/guides/concepts/assurance) for details.
</ParamField>

<ParamField query="match_request" type="string">
  Required when initiating a match-capable provider over OIDC. A JWT carrying the values you want compared against the authoritative source.

  * **Algorithm**: `HS256`, signed with your `client_secret`.
  * **Payload claim**: `match_data` — an object whose keys are provider-native (see [`matchData` field schema](/api-reference/verifications/create-verification#param-match-data)).
  * **Other claims**: standard JWT (`iat`, `exp`, `jti`) and OAuth/OIDC params (`client_id`, `redirect_uri`, `state`, `nonce`, `scope`) may also be carried in the JWT; if present they take precedence over their query-string equivalents.

  ```json Decoded payload theme={null}
  {
    "client_id": "YOUR_CLIENT_ID",
    "match_data": {
      "fullName": "Test User",
      "dateOfBirth": "1990-01-01"
    },
    "iat": 1714060000,
    "exp": 1714060300
  }
  ```

  The result is returned via the standard userinfo flow with `verification_model: "match"` — see [Return Data Model](/guides/concepts/return-data-model#verification-models).
</ParamField>

## Behavior

* If successful, responds with `302 Found` to your `redirect_uri` with `code` and `state` query params.
* On failure, redirects with `error` and `error_description` (and `state` if provided).

## Examples

<RequestExample>
  ```http theme={null}
  GET https://sandbox.connect.hopae.com/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&response_type=code&scope=openid%20profile&state=rf9Xy1&code_challenge=AbCdEf...&code_challenge_method=S256
  ```
</RequestExample>

<ResponseExample>
  ```http theme={null}
  HTTP/1.1 302 Found
  Location: https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=rf9Xy1
  ```
</ResponseExample>

<ResponseExample>
  ```http theme={null}
  HTTP/1.1 302 Found
  Location: https://app.example.com/callback?error=access_denied&error_description=User%20cancelled%20login&state=rf9Xy1
  ```
</ResponseExample>