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

User ОАuth Flow

Aurinko's User OAuth Flow enables user-delegated authorization, producing a user session token or httpOnly cookie for managing application user sessions.

PreviousAccount OAuth FlowNextService Account OAuth Flow

Last updated 1 month ago

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 userSession 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 &accountRole=primary parameter)

  • Authorizing a secondary account for an existing user (use &accountRole=secondary 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 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.

  1. Authorization request

From your application, redirect users to https://api.aurinko.io/v1/auth/authorizeUser, with the query parameters used by the Account OAuth and specify the additional &accountRole=primary parameter. Set responseType to code or cookie (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} 

  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 user session

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

  • Cookie Mode (responseType=cookie)

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

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

  • Authorization Code Mode (responseType=code)

    If your authentication was 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 a userSession and userId.

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

Response:

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

See for details. Make sure to securely store the userSession and provide it as an API Key in the X-Aurinko-Session header to make API calls on behalf of the user (see details).

/auth/token
Authentication