Yoxel Accounts API

openapi: 3.2.0
info:
  contact:
    email: support@aurinko.io
  description: '## Introduction

    The Aurinko API is a unified API platform allowing developers to quickly build integrations with

    many mailbox providers and services like Google, Office 365, Outlook.com, MS Exchange, IMAP.

    The unified API abstracts away differences between many email, calendar, contact, task APIs

    to make it easy to connect and sync the mailbox data.


    The Aurinko API''s focus is convenient and reliable data synchronization for all supported

    data categories (email, calendar, contacts, tasks) so the API provides methods to receive changes/deltas

    and be notified of the changes (through webhooks) in a unified manner. The API''s sync/deltas model

    should allow developers to build reliable event based solutions easily.


    The Aurinko API is built on HTTP. Our API is RESTful. It has predictable resource URLs.

    It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body.


    ## API Authentication

    When you sign up for an account, you are given a Client Id and Secret

    for every application that you create. You use those to go through OAuth flows that allow you

    to start syncing remote account data through Aurinko. An account OAuth flow can be started with

    just the Client Id and the Client Secret will be required to obtain an account access token in the

    "authorization code" flow ("implicit grant" flow does is secured by the "trusted domains" setting).


    Aurinko offers two forms of authentication:


    - `Basic ` - used for authentication flows and administrative requests made from the server side.

    - `Bearer ` - used for working with an account data.

    - `Api Key in Cookie` - for in-browser apps that use Aurinko as their backend API with user sessions.

    - `Api Key in Header (X-Aurinko-Session)` - for server side apps that need user sessions


    Never share your client secret or access token. Keep them guarded and secure.


    ## Getting Started Guide

    If you have a use case you would like to implement, please consult us for feedback on the best API operations for the task.


    Click here to visit our API Guides.'
  termsOfService: https://www.aurinko.io/terms-of-service/
  title: Aurinko.io Accounts API
  version: 1.0.0
servers:
- url: https://api.aurinko.io
  description: Production server
security:
- AccountToken: []
- AppAuth: []
  AccountIdHeader: []
- UserSessionHeader: []
  AccountIdHeader: []
- UserSessionCookie: []
  ClientIdHeader: []
  AccountIdHeader: []
- AuthTypeHeader: []
  ExchangeIdToken: []
  ClientIdHeader: []
  AccountIdHeader: []
tags:
- name: Accounts
  description: These endpoints allow for account management outside the developer console interface. You can list, cancel, update, and delete accounts associated with your application.
paths:
  /v1/am/accounts:
    post:
      operationId: upsertPersonal
      tags:
      - Accounts
      summary: Upsert an account
      security:
      - AppAuth: []
      parameters:
      - schema:
          type:
          - core.client.user.useraccounttype.useraccounttype
          - 'null'
          $ref: '#/components/schemas/UserAccountType'
        in: query
        name: userAccount
        required: false
      - schema:
          type:
          - string
          - 'null'
        in: query
        name: userId
        description: ID of a user this account should be attached to.
        required: false
      - schema:
          type:
          - array
          - 'null'
          items:
            type: servicekey
            $ref: '#/components/schemas/ServiceKey'
        in: query
        name: recycleKeys
        required: false
      - schema:
          type:
          - boolean
          - 'null'
        in: query
        name: ensureAccess
        description: When set to true, Aurinko will check if a user has access to the requested resources. Supported only for Google and Office365, and only for Email, Calendar, Contacts and Tasks APIs.
        required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiAccountInDto'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountSaveResult'
        '401':
          $ref: '#/components/responses/UnauthorizedError2'
    get:
      operationId: getAccounts
      tags:
      - Accounts
      summary: Get accounts
      security:
      - AppAuth: []
      parameters:
      - schema:
          default: 50
          format: int32
          type:
          - integer
          - 'null'
        in: query
        name: limit
        description: page size
        required: false
      - schema:
          default: 0
          format: int32
          type:
          - integer
          - 'null'
        in: query
        name: offset
        description: return records offset by the given number
        required: false
      - schema:
          type:
          - string
          - 'null'
        in: query
        name: authOrgId
        description: An authenticated OrgId
        required: false
      - schema:
          type:
          - core.client.servicetype
          - 'null'
          $ref: '#/components/schemas/ServiceTypeNonDaemon'
        in: query
        name: serviceType
        required: false
      - schema:
          format: int64
          type:
          - integer
          - 'null'
        in: query
        name: subscriptionId
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountsPage'
        '401':
          $ref: '#/components/responses/UnauthorizedError2'
      x-codeSamples:
      - lang: cURL
        source: "curl -u ClientId:Secret -X GET https://api.aurinko.io/v1/am/accounts \\\n    -G -d clientOrgId='12345'"
  /v1/am/accounts/{id}:
    get:
      operationId: getAccount
      tags:
      - Accounts
      summary: Get account by id
      security:
      - AppAuth: []
      parameters:
      - schema:
          format: int64
          type: integer
        in: path
        name: id
        description: account id
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAccountOutDto'
        '401':
          $ref: '#/components/responses/UnauthorizedError2'
      x-codeSamples:
      - lang: cURL
        source: curl -u ClientId:Secret -X GET https://api.aurinko.io/v1/am/accounts/{id}
    delete:
      operationId: amAccountDelete
      tags:
      - Accounts
      summary: Delete account by ID
      security:
      - AppAuth: []
      responses:
        '200':
          description: Success
        '401':
          $ref: '#/components/responses/UnauthorizedError2'
      x-codeSamples:
      - lang: cURL
        source: curl -u ClientId:Secret -X DELETE https://api.aurinko.io/v1/am/accounts/12345
      parameters:
      - in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
components:
  schemas:
    Scope:
      type: string
      enum:
      - Calendar.Read
      - Calendar.ReadWrite
      - Mail.Read
      - Mail.ReadWrite
      - Mail.Send
      - Mail.Drafts
      - Mail.All
      - Contacts.Read
      - Contacts.ReadWrite
      - Tasks.Read
      - Tasks.ReadWrite
      description: Space separated list of scopes
    ServiceType:
      type: string
      enum:
      - Google
      - GoogleBot
      - Office365
      - EWS
      - IMAP
      - Salesforce
      - Salesflare
      - Repfabric
      - MsTeamsBot
      - Slack
      - SlackBot
      - SugarCRM
      - HighLevel
      - Hubspot
      - Zoom
      - ZoomBot
      - Webex
      - WebexBot
      - Pipedrive
      - EclipseERP
      - AutoQuotes
      - Teamwork
      - NetSuite
      - MCTrade
      - SpecPath
      - Zoho
      - Clientify
      - QuickBooks
      - ActiveCampaign
      - Creatio
      - ConstantContact
      - Fishbowl
      - iCloud
    ServiceKey:
      type: string
      enum:
      - email
      - orgId
      - userId
      - serverUrl
      - username
      - clientOrgId
      description: Keys that control account re-cycling.
    ApiAccountInDto:
      type: object
      required:
      - serviceType
      - active
      properties:
        serviceType:
          $ref: '#/components/schemas/ServiceType'
        authScopes:
          type: array
          items:
            $ref: '#/components/schemas/Scope'
        authOrgId:
          type: string
        authUserId:
          type: string
        clientOrgId:
          type: string
        serverUrl:
          type: string
        loginString:
          type: string
          description: This or email field must be specified
        oauthClientId:
          type: string
        active:
          type: boolean
          description: The account is always active in the current API version
        authString1:
          type: string
        authString2:
          type: string
        password:
          type: string
          description: Password for IMAP accounts
        authObtainedAt:
          type: string
          format: date-time
        authExpiresAt:
          type: string
          format: date-time
        email:
          type: string
          description: This or loginString field must be specified
        name:
          type: string
        serverInfo:
          type: string
        timezone:
          type: string
    AccountsPage:
      type: object
      properties:
        offset:
          type: integer
        totalSize:
          type: integer
        done:
          type: boolean
        records:
          type: array
          items:
            $ref: '#/components/schemas/ApiAccountOutDto'
    NativeScope:
      type: string
      description: Native scope from provider's API.
    ServiceTypeNonDaemon:
      type: string
      enum:
      - Google
      - Office365
      - EWS
      - IMAP
      - Salesforce
      - Salesflare
      - Repfabric
      - Slack
      - SugarCRM
      - HighLevel
      - Hubspot
      - Zoom
      - Webex
      - WebexBot
      - Pipedrive
      - EclipseERP
      - AutoQuotes
      - Teamwork
      - NetSuite
      - SpecPath
      - Zoho
      - Clientify
      - QuickBooks
      - ActiveCampaign
      - Creatio
      - ConstantContact
      - Fishbowl
      - iCloud
    AccountType:
      type: string
      enum:
      - daemon
      - personal
      - managed
    ApiAccountOutDto:
      type: object
      properties:
        id:
          type: integer
          format: int64
        parentId:
          type: integer
          format: int64
        serviceType:
          $ref: '#/components/schemas/ServiceType'
        active:
          type: boolean
          description: The account is always active in the current API version
        tokenStatus:
          $ref: '#/components/schemas/TokenStatus'
        tokenError:
          type: string
        type:
          $ref: '#/components/schemas/AccountType'
        daemon:
          type: boolean
        loginString:
          type: string
        email:
          type: string
        mailboxAddress:
          type: string
        name:
          type: string
        name2:
          type: string
        serverUrl:
          type: string
        serverUrl2:
          type: string
        clientOrgId:
          type: string
        authUserId:
          type: string
        authOrgId:
          type: string
        timezone:
          type: string
        tokenIssuedAt:
          type: string
          format: date-time
        authScopes:
          type: array
          items:
            $ref: '#/components/schemas/Scope'
        authNativeScopes:
          type: array
          items:
            $ref: '#/components/schemas/NativeScope'
        authObtainedAt:
          type: string
          format: date-time
        authExpiresAt:
          type: string
          format: date-time
        userId:
          type: string
    TokenStatus:
      type: string
      enum:
      - active
      - invalid
      - dead
      description: "* active - means the token is active and ready for use\n* invalid - means that Aurinko failed to access provider API with authentication data.\n   Basically it indicates that Aurinko has received a 401 http status from provider and marked this token as non-active.\n* dead - this is a special variant of \"invalid\" status that can occur only with OAuth 2.0 accounts.\n   It means that Aurinko failed to refresh OAuth access token and received \"invalid_grant\" error which indicates\n   that the access/refresh tokens pair cannot be used anymore and is basically dead.\n   The difference between invalid and dead is that with invalid tokens Aurinko will still try to\n   access provider API and with dead Aurinko won't even attempt:\n   trying to use dead token, Aurinko will just return 401 without making calls to the provider.\n"
    AccountSaveResult:
      type: object
      properties:
        accountId:
          type: integer
          format: int64
        accessToken:
          type: string
        userId:
          type: string
        userSession:
          type: string
    UserAccountType:
      type: string
      enum:
      - primary
      - secondary
      description: Type of user account. Required if `userId` is provided.
  responses:
    UnauthorizedError2:
      description: Authentication information is missing or invalid
      headers:
        WWW_Authenticate:
          schema:
            type: string
  securitySchemes:
    AppAuth:
      type: http
      scheme: basic
      description: App-level basic authentication using Client ID and Client Secret that can be obtained at Aurinko Dashboard page.
    AccountToken:
      type: http
      scheme: bearer
      description: Account-level authentication with account token obtained using `/auth/authorize` endpoint.
    UserSessionCookie:
      type: apiKey
      in: cookie
      name: AUR{APPID}
      description: Cookie-based user-level authentication
    UserSessionHeader:
      type: apiKey
      in: header
      name: X-Aurinko-Session
      description: Token-based user-level authentication
    ClientIdHeader:
      type: apiKey
      in: header
      name: X-Aurinko-Client-Id
      description: Client ID that can be obtained at Aurinko Dashboard page
    AccountIdHeader:
      type: apiKey
      in: header
      name: X-Aurinko-Account-Id
      description: User account id
    AuthTypeHeader:
      type: apiKey
      in: header
      name: X-Aurinko-Auth-Type
      description: 'Authentication type. Possible values: default, exchangeIdToken'
    ExchangeIdToken:
      type: http
      scheme: bearer
      bearerFormat: 'Exchange Identity Token (only with `X-Aurinko-Auth-Type: exchangeIdToken` header.)'
      description: 'Authentication using Exchange Identity Token. To use this method `X-Aurinko-Auth-Type: exchangeIdToken` header should be used.'
x-tagGroups:
- name: OAuth Flow
  tags:
  - Auth
  - Account
  - User
- name: Account management
  tags:
  - Accounts
  - Services
  - Managed accounts
- name: Email
  tags:
  - Messages
  - EmailSync
  - Drafts
  - EmailFolders
  - EmailTracking
  - FollowUpRobot
- name: Calendars
  tags:
  - Calendars
  - Events
  - CalSync
  - FreeBusySchedule
- name: Scheduling
  tags:
  - Booking
  - GroupBooking
  - Availability
- name: Contacts
  tags:
  - Contacts
  - ContSync
- name: Tasks
  tags:
  - TaskLists
  - Tasks
  - TaskSync
- name: Webhooks
  tags:
  - Webhooks
- name: Other
  tags:
  - Errors