> For the complete documentation index, see [llms.txt](https://docs.aurinko.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aurinko.io/authentication/oauth-flow/user-oauth-flow.md).

# User ОАuth Flow

Aurinko provides multiple Unified OAuth Flows that аre backed by providers' OAuth2 (i.e. Google, Office 365, Zoho Mail, Salesforce, HubSpot, SugarCRM) or by secure password-based authentication (i.e. MS Exchange, IMAP accounts).

## User OAuth Flow

***

This flow uses a user-delegated authorization and produces an Aurinko User with a user session token or httpOnly cookie. This flow is designed for managing application users (user sessions).

The user session token <mark style="color:red;">`userSession`</mark> or the httpOnly cookie is used to access the app user session and all its linked accounts. Two main operations are supported:

* Authorizing a primary account and initializing a user session (use <mark style="color:red;">`&accountRole=primary`</mark> parameter)
* Authorizing a secondary account for an existing user (use <mark style="color:red;">`&accountRole=secondary`</mark> parameter)

Some key terms you'll encounter while integrating with Aurinko's OAuth2 flow:

#### **Final Callback URL (returnUrl)**

The final callback URL, also known as <mark style="color:red;">`returnUrl`</mark>, is the URL provided by your application and specified when calling the <mark style="color:red;">`/authorize`</mark> API method within Aurinko. This is where Aurinko will redirect the user after successful authorization. It's crucial to register this URL within the Aurinko settings for your application.

#### Intermediate Redirect URL

The intermediate redirect URL is a temporary landing page used during the OAuth2 flow. By default, Aurinko uses <mark style="color:red;">`https://api.aurinko.io/v1/auth/callback`</mark> for this purpose. However, developers have the flexibility to customize this URL within the Aurinko settings for their application.

The following diagram shows a custom OAuth flow with your own intermediate redirect URL.&#x20;

<figure><img src="/files/wZOTmjrD9VEtHDc9hfLz" alt=""><figcaption></figcaption></figure>

1. **Authorization request**

From your application, redirect users to <mark style="color:red;">`https://api.aurinko.io/v1/auth/authorizeUser`</mark>, with the query parameters used by the Account OAuth and specify the additional <mark style="color:red;">`&accountRole=primary`</mark> parameter. Set <mark style="color:red;">`responseType`</mark> to <mark style="color:red;">`code`</mark> or <mark style="color:red;">`cookie`</mark> (default value if not set).

*Here's an example authorization request for creating a user* :

```
https://api.aurinko.io/v1/auth/authorizeUser?clientId={appClientId}
    &accountRole=primary
    &serviceType=Google
    &scopes=Mail.Read%20Mail.Send
    &returnUrl=...
    &state={state} 
```

*Adding a secondary account (assuming the user session cookie is already set):*

```
https://api.aurinko.io/v1/auth/authorizeUser?clientId={appClientId}
    &accountRole=secondary
    &serviceType=Hubspot
    &returnUrl=...
    &state={state} 
```

2. **User Consent**

Aurinko will present your user with the correct sign-in form based on the requested service type (Google, Office365, EWS). For Exchange users, the user has to enter a login name and an Exchange server url.

3. **Getting the user session**

Once the user has signed in and authorized your app's access, their browser will be redirected to the <mark style="color:red;">`returnUrl`</mark> you provided.

* **Cookie Mode** (<mark style="color:red;">`responseType=cookie`</mark>)

  If your authentication was successful Aurinko will set a secure httpOnly session cookie before redirecting to you returnUrl.

  *Example redirect URL*: <mark style="color:red;">`https://your-app.com/callback?state={state}&status=success`</mark>
* **Authorization Code Mode** (<mark style="color:red;">`responseType=code`</mark>)

  If your authentication was successful Aurinko will include the `code` parameter in the query string.

  *Example redirect URL*: <mark style="color:red;">`https://your-app.com/callback?code={code}&state={state}&status=success`</mark>

  Make an HTTP POST call to <mark style="color:red;">`https://api.aurinko.io/v1/auth/token/{code)}`</mark> to exchange the <mark style="color:red;">`code`</mark> for a <mark style="color:red;">`userSession`</mark> and <mark style="color:red;">`userId`</mark>.

```bash
    curl -u ClientId:Secret -X POST https://api.aurinko.io/v1/auth/token/{code}
```

*Response:*

```json
{
    "accountId": 123,
    "accessToken": "aurinko-access-token",
    "userId": "user-id-xyz",
    "userSession": "user-session-token"
 }
```

See [/auth/token](https://apirefs.aurinko.io/#tag/Auth/operation/getAccessTokenByCode) for details. Make sure to securely store the <mark style="color:red;">`userSession`</mark> and provide it as an API Key in the <mark style="color:red;">`X-Aurinko-Session`</mark> header to make API calls on behalf of the user (see [Authentication](https://apirefs.aurinko.io/#section/Authentication) details).