# Service Account OAuth Flow

Aurinko provides multiple Unified OAuth Flows 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).

## Service Account OAuth Flow

***

This flow is for gaining admin/app-level access, usually requiring a Google/Office 365 admin authorization. See the following instructions related to service accounts: [Service accounts](/authentication/service-accounts.md), [Setting up G Suite service account](http://helpdocs.yoxel.com/salesforce/setting-up-g-suite-service-account), and [Setting up Office 365 daemon app registration](/authentication/service-accounts/setting-up-office-365-daemon-app-registration.md).

The flow produces an Aurinko <mark style="color:red;">`service account`</mark> 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>

1. **Authorization request**

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

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:

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

***Redirect URI: Redirect page vs. Custom domain alias***

In case your Microsoft app registration requires redirect URIs to be under a domain you own the default Aurinko's Redirect URI <https://api.aurinko.io/v1/auth/callback> may not work for you in production.

<div data-full-width="true"><figure><img src="/files/7YXqxNofltV05kq6jEWs" alt=""><figcaption></figcaption></figure></div>

You have two options:

* Contact us about provisioning a domain alias for your Aurinko app so you can use a URL like <mark style="color:red;">`https://aurinko.mydomain/v1/auth/callback`</mark>
* Create your **intermediate redirect** page to use for redirecting all calls 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>. See the corresponding OAuth flow in the following diagram:

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

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.

* **Authorization Code Grant** (<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 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 account (see [Authentication](https://apirefs.aurinko.io/#section/Authentication) details).


---

# 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/service-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.