# Account OAuth Flow

## Account OAuth Flow

***

This is a standard flow for getting access to a remote account. To enable Google and Office 365 OAuth flow for production, please see the following instructions [Office365 OAuth Setup](/authentication/office-365-oauth-setup.md) and [Google OAuth Setup](/authentication/google-oauth-setup.md).

This flow uses user-delegated authorization and produces an Aurinko account and an access token.

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>

We recommend this flow because Google app registrations allow only authorized redirect URIs under a domain you own so Aurinko's default Redirect URI <mark style="color:red;">`https://api.aurinko.io/v1/auth/callback`</mark> won't work for you in production.

Create a dedicated **intermediate redirect** page that will be redirecting all callback requests to Aurinko's <mark style="color:red;">`https://api.aurinko.io/v1/auth/callback`</mark> with the URL parameters <mark style="color:red;">`state`</mark>, <mark style="color:red;">`code`</mark>, and <mark style="color:red;">`scope`</mark>. \
\
Specify the page url in the Aurinko app settings (override the default url).

<div align="left" data-full-width="true"><figure><img src="/files/WbYMBAvMciBMdnkUSpMi" alt=""><figcaption></figcaption></figure></div>

1. #### [Authorization request](#user-content-fn-1)[^1]

From your application, redirect users to <mark style="color:red;">`https://api.aurinko.io/v1/auth/authorize`</mark>, with the query parameters detailed in [/auth/authorize](https://apirefs.aurinko.io/#tag/Auth/operation/authorize). You'll need to set the <mark style="color:red;">`responseType=code`</mark>.

{% hint style="info" %}
Note: <mark style="color:red;">`responseType=token`</mark> for client-side flows (corresponding to the OAuth's implicit grant) is supported but is not recommended!
{% endhint %}

You'll also need to determine what permissions your application will request from users, and update the <mark style="color:red;">`scopes`</mark> query parameter accordingly. Aurinko provides granular authentication scopes that empower users with control over what level of access your application has to their data. See supported [Authentication scopes](/authentication/authentication-scopes.md) for details.

Here's an example of what this URL might look like once you've included all the correct query parameters:

```html
https://api.aurinko.io/v1/auth/authorize?clientId={appClientId}&
      &serviceType=Google
      &scopes=Mail.Read%20Mail.Send
      &responseType=code
      &returnUrl=...
      &state={myCustomState}
```

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 token

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.

* **Implicit Grant** (<mark style="color:red;">`responseType=token`</mark>)

  If the authentication is successful Aurinko will include the hash fragment <mark style="color:red;">`#accessToken={accessToken}`</mark> with the account access token. That's it!

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

  We recommend storing the `accessToken` and then removing it from the hash fragment with JavaScript. This is the token you will provide as an <mark style="color:red;">`HTTP Bearer Auth`</mark> to make API calls on behalf of the user.
* **Authorization Code Grant** (<mark style="color:red;">`responseType=code`</mark>)

  If the authentication is 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 an <mark style="color:red;">`access_token`</mark>.

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

*Response:*

```json
{
	"accountId": 123,
	"accessToken": "aurinko-account-token",
}
```

\
See [/auth/token](https://apirefs.aurinko.io/#tag/Auth/operation/getAccessTokenByCode) for details. Make sure to securely store the <mark style="color:red;">`accessToken`</mark> and provide it as the <mark style="color:red;">`HTTP Bearer Auth`</mark> token to make API calls on behalf of the user (see [Authentication](https://apirefs.aurinko.io/#section/Authentication) details).

[^1]:


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aurinko.io/authentication/oauth-flow/account-oauth-flow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.