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

# Authorize User

> Starts the OAuth 2.0 Authorization Code flow.

Open this endpoint in the user's browser. Eka authenticates the user when
required and redirects the browser to the registered `redirect_uri`.
A successful redirect contains a short-lived, single-use authorization
`code` that your backend exchanges at `/oauth2/token`.

Eka grants a fixed scope set on this endpoint. Include it as the OAuth
`scope` query parameter:
`openid profile email offline_access`.

PKCE is optional. When using PKCE, use the `S256` challenge method and
generate a new verifier for every authorization request.


<Note>
  Open this endpoint in the user's browser. Do not call it as a backend API.
</Note>

Use the Authorization Code flow. PKCE is optional. If you use PKCE, use
`code_challenge_method=S256` and generate a new verifier for every authorization request.
After authentication, Eka redirects the browser to your registered `redirect_uri` with a
single-use authorization code.

Your client application should verify `state` before exchanging the code. If your authorization
request includes a `nonce`, your client should verify it when validating the returned ID token.

<Info>
  Eka always grants this fixed scope set. Include it as the `scope` query parameter:
  `openid profile email offline_access`.
</Info>


## OpenAPI

````yaml get /oauth2/authorize
openapi: 3.0.3
info:
  title: Eka OIDC Provider
  version: 1.0.0
  description: OAuth 2.0 and OpenID Connect endpoints for signing users in with Eka.
servers:
  - description: Production
    url: https://accounts.eka.care
  - description: Stage/Sandbox
    url: https://aortago.dev.eka.care
security: []
tags:
  - name: Eka OIDC Provider
paths:
  /oauth2/authorize:
    get:
      tags:
        - Eka OIDC Provider
      summary: Authorize a user
      description: >
        Starts the OAuth 2.0 Authorization Code flow.


        Open this endpoint in the user's browser. Eka authenticates the user
        when

        required and redirects the browser to the registered `redirect_uri`.

        A successful redirect contains a short-lived, single-use authorization

        `code` that your backend exchanges at `/oauth2/token`.


        Eka grants a fixed scope set on this endpoint. Include it as the OAuth

        `scope` query parameter:

        `openid profile email offline_access`.


        PKCE is optional. When using PKCE, use the `S256` challenge method and

        generate a new verifier for every authorization request.
      operationId: authorize
      parameters:
        - name: response_type
          in: query
          required: true
          description: Use `code` for the Authorization Code flow.
          schema:
            type: string
            enum:
              - code
          example: code
        - name: client_id
          in: query
          required: true
          description: Client identifier issued by Eka.
          schema:
            type: string
          example: EC_178843954824934
        - name: redirect_uri
          in: query
          required: true
          description: |
            Callback URL that receives the authorization response. It must
            exactly match a redirect URI registered for the client.
          schema:
            type: string
            format: uri
          example: http://localhost:50515/auth-success
        - name: scope
          in: query
          required: true
          description: |
            Fixed scope set for this endpoint:
            `openid profile email offline_access`.
          schema:
            type: string
            default: openid profile email offline_access
            enum:
              - openid profile email offline_access
        - name: state
          in: query
          required: true
          description: >
            Unpredictable value used by the client to prevent CSRF. Verify that

            the same value is returned to the callback. Use at least 8
            characters.
          schema:
            type: string
            minLength: 8
          example: 1f0c7c8d2f7741b8
        - name: nonce
          in: query
          required: false
          description: |
            Unpredictable value that binds the client session to the ID token.
            Verify the returned ID token contains the same value.
          schema:
            type: string
          example: e85f0c29a1bb49c9
        - name: code_challenge
          in: query
          required: false
          description: |
            Base64url-encoded SHA-256 digest of the PKCE `code_verifier`.
            Required only when using PKCE.
          schema:
            type: string
          example: 6GcavjuHpQj-Z2MxhtG12eF1KDMeaJ1a5xxyh8z1leY
        - name: code_challenge_method
          in: query
          required: false
          description: PKCE transformation method. Use `S256`.
          schema:
            type: string
            enum:
              - S256
          example: S256
        - name: prompt
          in: query
          required: false
          description: Set to `login` to require the user to authenticate again.
          schema:
            type: string
            enum:
              - login
          example: login
        - name: max_age
          in: query
          required: false
          description: >
            Maximum allowed age of the user's Eka authentication session, in

            seconds. Eka requires authentication again when the session is
            older.

            A value of `0` always requires authentication.
          schema:
            type: integer
            format: int64
            minimum: 0
          example: 3600
      responses:
        '303':
          description: >
            The browser is redirected to `redirect_uri`. On success, the query

            contains `code`, `state`, and the granted `scope`. On an OAuth
            error,

            it contains `error`, `error_description`, and `state`.
          headers:
            Location:
              description: Client callback URL containing the authorization response.
              schema:
                type: string
                format: uri
              example: >-
                http://localhost:50515/auth-success?code=ory_ac_example&state=1f0c7c8d2f7741b8
        '307':
          description: >-
            The browser is redirected to Eka login when authentication is
            required.
          headers:
            Location:
              description: Eka login URL.
              schema:
                type: string
                format: uri
        '400':
          description: Invalid request when a safe client redirect cannot be performed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
components:
  schemas:
    OAuthError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: invalid_grant
        error_description:
          type: string
          example: >-
            The provided authorization grant is invalid, expired, or already
            used.

````