Aurinko
Aurinko websiteAurinko blogAPI ReferenceContact Support
Aurinko API
Aurinko API
  • Getting started
    • What is Unified Mailbox API?
    • Getting started with Aurinko
    • Get your developer API keys
    • Adding Aurinko to Google Workspace allowlist
    • Bubble.io plugin
    • Team members and roles in applications
  • Unified APIs
    • Email API
    • Calendar API
    • Contacts API
    • Tasks API
    • Webhooks API
      • Configuring Pub/Sub for Gmail API Webhooks
    • Direct API
  • Authentication
    • OAuth Flow
      • Account OAuth Flow
      • User ОАuth Flow
      • Service Account OAuth Flow
    • Authentication scopes
    • Authorized return URLs
    • Google OAuth setup
    • Office 365 OAuth setup
    • ZOHO OAuth setup
    • Service accounts
      • Setting up G Suite service account
      • Setting up Office 365 daemon app registration
  • Scheduling
    • Create your first appointment booking page
    • Calendar Booking Page
    • Booking API
    • Group Booking API
  • Workspace Addons
    • Outlook addins
      • Create your first Outlook addin
      • Office 365: Installing Outlook addin
    • Microsoft Teams apps
      • Microsoft Teams bot setup
      • Create your first MS Teams app
      • Installing MS Teams app
    • Chrome Extensions with Google authentication
    • Google Workspace Add-Ons
  • Dynamic API
    • What is Dynamic (Virtual) API?
    • Getting Started with Dynamic API
Powered by GitBook
On this page
  1. Authentication
  2. OAuth Flow

Account OAuth Flow

Aurinko's Account OAuth Flow is a user-delegated authorization flow, producing an Aurinko account and an access token for secure API access.

PreviousOAuth FlowNextUser ОАuth Flow

Last updated 2 months ago

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 and .

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 returnUrl, is the URL provided by your application and specified when calling the /authorize 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 https://api.aurinko.io/v1/auth/callback 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.

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

Create a dedicated intermediate redirect page that will be redirecting all callback requests to Aurinko's https://api.aurinko.io/v1/auth/callback with the URL parameters state, code, and scope. Specify the page url in the Aurinko app settings (override the default url).

Note: responseType=token for client-side flows (corresponding to the OAuth's implicit grant) is supported but is not recommended!

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/authorize?clientId={appClientId}&
      &serviceType=Google
      &scopes=Mail.Read%20Mail.Send
      &responseType=code
      &returnUrl=...
      &state={myCustomState}

  1. 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.

  1. Getting the token

Once the user has signed in and authorized your app's access, their browser will be redirected to the returnUrl you provided.

  • Implicit Grant (responseType=token)

    If the authentication is successful Aurinko will include the hash fragment #accessToken={accessToken} with the account access token. That's it!

    Example redirect URL: https://your-app.com/callback?#accessToken={token}&state={state}&status=success

    We recommend storing the accessToken and then removing it from the hash fragment with JavaScript. This is the token you will provide as an HTTP Bearer Auth to make API calls on behalf of the user.

  • Authorization Code Grant (responseType=code)

    If the authentication is successful Aurinko will include the code parameter in the query string.

    Example redirect URL: https://your-app.com/callback?code={code}&state={state}&status=success

    Make an HTTP POST call to https://api.aurinko.io/v1/auth/token/{code} to exchange the code for an access_token.

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

Response:

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

From your application, redirect users to https://api.aurinko.io/v1/auth/authorize, with the query parameters detailed in . You'll need to set the responseType=code.

You'll also need to determine what permissions your application will request from users, and update the scopes 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 for details.

See for details. Make sure to securely store the accessToken and provide it as the HTTP Bearer Auth token to make API calls on behalf of the user (see details).

/auth/authorize
Authentication scopes
/auth/token
Authentication
Office365 OAuth Setup
Google OAuth Setup