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

# Get the OAuth authorize URLs

> Returns the provider authorize URLs to send the end user to. Open the
returned URL in a browser to start the sign-in.

The response contains a key only for each provider enabled on the
environment, so an environment with Google enabled and Apple disabled
returns `google` only. An environment with neither enabled returns an
empty object.




## OpenAPI

````yaml /openapi/authentication-api.yaml get /oauth/urls
openapi: 3.1.0
info:
  title: Portal Authentication API
  version: '3.0'
  description: |
    The Portal Authentication API signs in your end users with an email magic
    link, Google, or Apple. A completed sign-in returns a Client Session Token
    that your app uses to create and operate the user's wallet.

    ## Base URL
    `https://api.portalhq.io/api/v3/auth`

    ## Authentication
    These endpoints do not use a Portal API Key or a Client Session Token.
    Identify your environment with the `x-portal-auth-environment-id` header,
    set to the Auth Environment ID shown in the Portal dashboard under
    **Authentication > Configure**.

    Requests are rejected with `401` if the header is missing, if it does not
    match an environment, or if authentication is not enabled for that
    environment.

    ## Response format
    Successful responses are wrapped in a `data` object, alongside a `metadata`
    field that is `null` for every endpoint in this API:

    ```json
    { "data": { "sent": true }, "metadata": null }
    ```

    ## Error responses
    Every authentication failure returns the same generic `401` body, with no
    indication of which check failed. This is deliberate, so a caller cannot
    distinguish an expired token from a forged one. Treat any `401` as "start
    the sign-in flow again".
servers:
  - url: https://api.portalhq.io/api/v3/auth
    description: Production
security:
  - authEnvironmentId: []
tags:
  - name: Auth Methods
    description: Discover which sign-in methods an environment has enabled
  - name: Magic Links
    description: Send and validate email magic links
  - name: OAuth
    description: Sign in with Google or Apple
  - name: Two-Factor Authentication
    description: Validate a time-based one-time password (TOTP) code
paths:
  /oauth/urls:
    get:
      tags:
        - OAuth
      summary: Get the OAuth authorize URLs
      description: |
        Returns the provider authorize URLs to send the end user to. Open the
        returned URL in a browser to start the sign-in.

        The response contains a key only for each provider enabled on the
        environment, so an environment with Google enabled and Apple disabled
        returns `google` only. An environment with neither enabled returns an
        empty object.
      operationId: getOAuthUrls
      parameters:
        - name: redirectUrl
          in: query
          required: true
          description: |
            Where to send the user after a completed sign-in. Must exactly match
            one of the environment's Redirect URLs.
          schema:
            type: string
            format: uri
          example: https://example.com/callback
      responses:
        '200':
          description: Authorize URLs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthUrlsResponse'
              example:
                data:
                  google: >-
                    https://accounts.google.com/o/oauth2/v2/auth?client_id=example.apps.googleusercontent.com&redirect_uri=https%3A%2F%2Fapi.portalhq.io%2Fapi%2Fv3%2Fauth%2Foauth%2Fcallback%2Fexample-auth-environment-id&response_type=code&scope=openid%20email%20profile
                  apple: >-
                    https://appleid.apple.com/auth/authorize?client_id=com.example.auth&redirect_uri=https%3A%2F%2Fapi.portalhq.io%2Fapi%2Fv3%2Fauth%2Foauth%2Fcallback%2Fexample-auth-environment-id&response_type=code&response_mode=form_post&scope=name%20email
                metadata: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: |
            Unauthorized. Returned when the environment header is invalid, when
            `redirectUrl` is not on the environment's allow list, or when a
            provider is enabled but its credentials have not been configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Unauthorized
components:
  schemas:
    OAuthUrlsResponse:
      type: object
      properties:
        data:
          type: object
          description: |
            Contains a key for each enabled provider only. Empty when neither
            Google nor Apple is enabled.
          properties:
            google:
              type: string
              format: uri
              description: |
                The Google authorize URL. Present only when Google is enabled.
            apple:
              type: string
              format: uri
              description: |
                The Apple authorize URL. Present only when Apple is enabled.
        metadata:
          type:
            - object
            - 'null'
          description: Always `null` for this endpoint.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
        details:
          type: object
          description: Additional context about the failure, when available
        code:
          type: string
          description: Machine-readable error code, when available
  responses:
    BadRequest:
      description: Bad request. A required field is missing or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: email must be a valid email address.
  securitySchemes:
    authEnvironmentId:
      type: apiKey
      in: header
      name: x-portal-auth-environment-id
      description: |
        The Auth Environment ID for the environment you are authenticating
        against. Find it in the Portal dashboard under
        **Authentication > Configure**.

````