> ## 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. Front-channel redirect. No Authorization header.

Start a verification by redirecting the user's browser to the shared `/v2/auth` endpoint with your app's `client_id`. Hopae hosts the verification UI, runs the eID flow, and returns the user to your `redirect_uri` with an authorization code.

## Query Parameters

<ParamField query="client_id" type="string" required>
  Your App ID.
</ParamField>

<ParamField query="redirect_uri" type="string" required>
  Exact match to a redirect URI registered for this app (Console → Developers → API Settings → Redirect URL Allowlist). Saving the app's allowlist takes effect immediately. See [Apps & Environments](/v2/guides/concepts/apps).
</ParamField>

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

<ParamField query="scope" type="string" required default="openid hopae">
  Space-delimited scopes. Include `openid` and `hopae` (or the equivalent `idv`). Without `hopae`/`idv`, the userinfo response contains no `user`, `provenance`, `match`, or `missing_claims`.
</ParamField>

<ParamField query="state" type="string">
  Opaque value echoed back on the redirect. Use it for CSRF protection.
</ParamField>

<ParamField query="nonce" type="string">
  Bound into the ID token. Recommended for browser-based clients.
</ParamField>

<ParamField query="prompt" type="string">
  `login` forces a fresh verification. Hopae never reuses a previous verification, so this is mainly for client libraries that expect it.
</ParamField>

<ParamField query="workflow_id" type="string">
  The workflow to run (Console → Workflow → copy the workflow ID). Defaults to the app's default workflow. The workflow decides which connections are offered and which claims are requested. An unknown explicit workflow produces `invalid_request`. An app with no workflow shows a hosted error page (`WORKFLOW_NOT_CONFIGURED`) and does not redirect back.
</ParamField>

<ParamField query="acr_values" type="string">
  Filter enabled connections by a minimum supported Level of Assurance: `urn:hopae:loa:{level}` (1 to 5). Hopae records the achieved level in `acr` / `hopae_loa`. If it is lower than requested, the verification is still finished, and userinfo requested with `provenance=true` carries `provenance._metadata.error.code = "loa_insufficient"` so you can decide. A filter leaving no eligible connection finishes with `invalid_request`. The v1 `urn:hopae:id:{providerId}` token is ignored on `/v2`: it neither narrows nor rejects. Use the `ui_*` pre-selection hints instead. See [Level of Assurance](/v2/guides/verifications/assurance).
</ParamField>

<ParamField query="ui_connection_id" type="string">
  Pre-select a connection so the user skips country and credential selection. Use the catalog connection id (for example `smart-id`) of a connection enabled in the workflow. An id that is not enabled simply means no pre-selection. Replaces the v1 `ui_provider` parameter. `ui_connection_instance_id` with the instance id (`conn_…`) is also accepted.
</ParamField>

<ParamField query="ui_provider_id" type="string">
  Catalog provider id. Pre-selects its single enabled connection. If none or several match, the hosted selection screen remains visible. Unlike REST creation, ambiguity does not return a 400.
</ParamField>

<ParamField query="ui_credential_id" type="string">
  Use with `ui_provider_id` to narrow to one credential. Hint precedence is instance → connection → provider. An unmatched connection hint does not fall through to the provider hint.
</ParamField>

<ParamField query="ui_country" type="string">
  Pre-select the country step (ISO 3166-1 alpha-2).
</ParamField>

<ParamField query="ui_skip_intro" type="boolean">
  `true` skips the hosted intro screen and lands on the selection step.
</ParamField>

<ParamField query="ui_hide_back_button" type="boolean">
  `true` hides the back button in the hosted UI.
</ParamField>

<ParamField query="private_mode" type="boolean">
  `true` runs the verification but blocks token and userinfo issuance (`403 AUTH_DATA_PROTECTED`). Use it when you only need the result recorded on Hopae's side.
</ParamField>

<Note>
  The v1 parameters `ui_provider`, `ui_auth_flow`, `ui_hide_header`, and `ui_need_consent` have no effect on v2. The hosted flow always runs country → credential → provider.
</Note>

## Behavior

* On success, responds with `302 Found` to your `redirect_uri` with `code` and `state` query params. The code is single-use and expires after 5 minutes.
* On failure or cancellation, redirects with `error=access_denied` and an `error_description`, plus `state` if provided. A missing or unregistered `redirect_uri` cannot be redirected and shows a hosted error page instead.

## Examples

<RequestExample>
  ```http theme={null}
  GET https://connect.hopae.com/v2/auth?client_id=xhdh8a13&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&response_type=code&scope=openid%20hopae&state=rf9Xy1&nonce=n-0S6_WzA2Mj&workflow_id=wf_01J8XJ4Q2R7TPX9K
  ```
</RequestExample>

<ResponseExample>
  ```http Success theme={null}
  HTTP/1.1 302 Found
  Location: https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=rf9Xy1&iss=https%3A%2F%2Fconnect.hopae.com
  ```
</ResponseExample>

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


## OpenAPI

````yaml GET /auth
openapi: 3.1.0
info:
  title: Hopae Connect OpenID Provider
  version: 2.0.0
servers:
  - url: https://connect.hopae.com/v2
    description: Hopae Connect
security: []
tags:
  - name: OIDC
paths:
  /auth:
    get:
      tags:
        - OIDC
      summary: Start Authorization
      operationId: authorize
      parameters:
        - name: client_id
          in: query
          required: true
          description: Your App ID.
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: true
          description: A redirect URI registered for the app.
          schema:
            type: string
        - name: response_type
          in: query
          required: true
          description: Must be `code`.
          schema:
            type: string
            enum:
              - code
            default: code
        - name: scope
          in: query
          required: true
          description: Include `openid` and `hopae`.
          schema:
            type: string
            default: openid hopae
        - name: state
          in: query
          required: false
          description: Echoed back on the redirect. Use it for CSRF protection.
          schema:
            type: string
        - name: nonce
          in: query
          required: false
          description: Bound into the ID token.
          schema:
            type: string
        - name: workflow_id
          in: query
          required: false
          description: Workflow to run. Defaults to the app's default workflow.
          schema:
            type: string
        - name: acr_values
          in: query
          required: false
          description: Minimum Level of Assurance, `urn:hopae:loa:{1-5}`.
          schema:
            type: string
        - name: ui_connection_id
          in: query
          required: false
          description: Pre-select a connection by catalog id, for example `smart-id`.
          schema:
            type: string
        - name: ui_country
          in: query
          required: false
          description: Pre-select the country (ISO 3166-1 alpha-2).
          schema:
            type: string
        - name: ui_skip_intro
          in: query
          required: false
          description: Skip the intro screen.
          schema:
            type: boolean
        - name: ui_hide_back_button
          in: query
          required: false
          description: Hide the back button.
          schema:
            type: boolean
      responses:
        '302':
          description: >-
            Redirect to `redirect_uri` with `code` and `state`, or with
            `error=access_denied`.
      security: []

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.