# Authorization

Start an authentication process. If the process is successful, an authorization code is returned to the redirect URI specified in the request. (See OIDC spec). For pushed authorization requests (PAR), provide request_uri returned by the PAR request endpoint instead of authorization parameters.

Endpoint: GET /oidc/auth

## Query parameters:

  - `client_id` (string, required)
    Client ID for which authentication is requested. For pushed authorization requests (PAR), the client ID should match the ID of the client that initiated the PAR flow.

  - `redirect_uri` (string)
    Required for authorization code flow. URI to redirect to upon completion of the authentication flow. This is the server GET endpoint used to call the token endpoint, and should accept code as a query parameter. This URI must also be configured as an allowed redirect URI in the Mosaic Admin Portal

  - `scope` (string)
    Required for authorization code flow. Scope of the requested access. Used to request specific user details like email. Must include openid and can include additional values (space delimited). offline_access scope allows refreshing access tokens.
    Enum: "openid", "email", "phone", "offline_access"

  - `response_type` (string)
    Required for authorization code flow. Response type requested for the authentication flow.
    Enum: "code"

  - `prompt` (string)
    For authorization code flow. Space-delimited, case-sensitive list of string values that specifies whether the Authorization Server prompts the end-user for reauthentication and consent.
    Enum: "login", "consent", "none"

  - `nonce` (string)
    For authorization code flow. A random value that is included in the authentication request from the client (e.g. browser) to mitigate replay attacks. It will be added to the id_token and the backend service should only accept id_tokens that include the same nonce value as the one included in the original request.

  - `state` (string)
    For authorization code flow. An opaque string that is used to maintain state between the request and the callback. It will be added to the redirect URI as a query parameter, which should be validated by your server to protect against cross-site request forgery (CSRF) attacks

  - `code_challenge` (string)
    Required for authorization code flow with PKCE. A hashed value of the 'code_verifier' required for PKCE

  - `code_challenge_method` (string)
    Required for authorization code flow with PKCE. The hashing mechanism used to transform a code_verifier into the code_challenge in PKCE flows, must be 'S256'

  - `resource` (string)
    For authorization code flow. Resource URI the authentication request is attempting to access, which is reflected in the audience (aud claim) of the access token. This must be configured as resource for the application.

  - `claims` (string)
    For authorization code flow. A stringified object used to request additional claims in the ID token, such as roles, permissions, and other user profile data.
The structure is per the OIDC Standard. For supported claims and how to request custom claims, see the ID Token Reference.
Note: You should stringify the value.
    Example: "{\"id_token\":{\"roles\":null}}"

  - `acr_values` (string)
    For authorization code flow. Requested ACR values, specified as a space-separated string. The acr claim of the resulting ID token will indicate which requirements were satisfied.
    Enum: "mfa", "phone_number", "urn:transmit:google_direct", "urn:transmit:apple_direct", "urn:transmit:facebook_direct", "urn:transmit:line_direct", "urn:transmit:centralized"

  - `createNewUser` (boolean)
    For authorization code flow. Indicates if a new user should be created if one doesn't already exist (or associated with the app if the user isn't already). Public sign up must be enabled for this application.

  - `login_hint` (string)
    For authorization code flow. Hint for the user's login identifier for WebAuthn login.
    Example: "user@acme.com"

  - `custom_message` (string)
    For authorization code flow. Custom message to present on the consent screens for WebAuthn login, which provides authentication context details.
    Example: "Welcome to Acme"

  - `ui_locales` (string)
    For authorization code flow. Preferred languages for the user interface for WebAuthn login, specified as a space-separated list of language tag values [RFC5646], ordered by preference.

  - `org_id` (string)
    For authorization code flow. Organization ID, used for member login in B2B scenarios

  - `request_uri` (string)
    Required for PAR flow. The URI returned by the PAR request. The request_uri value is bound to the client that sent the PAR authorization request.

  - `loginType` (string)
    For authorization code flow. Authentication method to be used for this process, where centralized is used to request authentication via the Authentication Hub.
    Enum: "google-direct", "apple-direct", "facebook-direct", "webauthn-direct", "line-direct", "centralized"

## Response 400 fields (application/json):

  - `message` (array, required)
    Example: "Bad request"

  - `error_code` (number, required)
    Example: 400

## Response 500 fields (application/json):

  - `message` (string, required)
    Example: "Something went wrong - Internal server error"

  - `error_code` (number, required)
    Example: 500


## Response 303 fields