Authorization
Documentation Powered by ReDoc

Global Accounts API (2.0.0)

Download OpenAPI specification:Download

API used to manage Organizations and Accounts for multiple products. Also responsible for authorization and authentication processes.

Authentication

Personal Access Token

Use your account_id as the username and the Personal Access Token (PAT) as the password. Learn how to get a PAT.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

OAuth2 Bearer Token

This API uses OAuth2 with the implicit grant flow. Learn about the implicit grant flow.

Security Scheme Type OAuth2
implicit OAuth Flow
Authorization URL: https://accounts.livechat.com
Scopes:
    authorizationCode OAuth Flow
    Authorization URL: https://accounts.livechat.com
    Token URL: https://accounts.livechat.com/token
    Scopes:

      Accounts

      List accounts

      Accounts are listed by using organization_id obtained from the access token. The accounts.roles--all:ro scope is required for listing accounts along with their roles.

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token (accounts--all:roaccounts.roles--all:ro)

      Responses

      Response samples

      Content type
      application/json
      [
      • {
        }
      ]

      Create a new account

      Create an account for a given organization_id. This endpoint is idempotent. The accounts.roles--all:rw scope is required to create an account with a role.

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token (accounts--all:rwaccounts--all:rcaccounts.roles--all:rw)
      Request Body schema: application/json
      name
      string <= 191 characters

      Account name (nick; first, second name; or both)

      email
      required
      string <email> <= 128 characters

      Account's email address

      default_product
      string
      Enum: "LiveChat" "Accounts"

      Available product name

      default_organization_id
      string <uuid> Nullable
      Default: null

      ID of default organization the account belongs to.

      avatar_url
      string <= 255 characters Nullable
      Default: null

      Account's avatar

      Array of objects or objects

      Array of account roles; returned only when the access token contains the accounts.roles--all:ro scope.

      password
      string [ 8 .. 255 ] characters

      Password for a given account

      Responses

      Request samples

      Content type
      application/json
      {
      • "name": "John",
      • "email": { },
      • "default_product": "Accounts",
      • "default_organization_id": "b2185556-634c-4ecf-b4c9-bcf8b65bc853",
      • "avatar_url": null,
      • "roles": [
        ],
      • "password": "BG0SaleEBL"
      }

      Response samples

      Content type
      application/json
      {
      • "account_id": "496a94f2-cbbf-444e-a3cb-305b9f5f8cbb",
      • "name": "John",
      • "email": "john@example.com",
      • "email_verified": false,
      • "default_product": "Accounts",
      • "default_organization_id": "b2185556-634c-4ecf-b4c9-bcf8b65bc853",
      • "avatar_url": null,
      • "roles": [
        ],
      • "updated_at": "2019-09-03T10:53:04.000Z",
      • "created_at": "2019-09-03T10:53:04.000Z"
      }

      Get an account

      Get an account for a given account_id. The ID can be replaced with me to get the account that performs the request. To get an account along with its role, you need the accounts.roles--all:ro scope.

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token (accounts--my:roaccounts.roles--all:ro)
      path Parameters
      account_id
      required
      string <uuid>

      Unique account ID or me

      Responses

      Response samples

      Content type
      application/json
      {
      • "account_id": "496a94f2-cbbf-444e-a3cb-305b9f5f8cbb",
      • "name": "John",
      • "email": "john@example.com",
      • "email_verified": false,
      • "default_product": "Accounts",
      • "default_organization_id": "b2185556-634c-4ecf-b4c9-bcf8b65bc853",
      • "avatar_url": null,
      • "roles": [
        ],
      • "updated_at": "2019-09-03T10:53:04.000Z",
      • "created_at": "2019-09-03T10:53:04.000Z"
      }

      Update an account

      Update an account for a given account_id. The ID can be replaced with me to update the account that performs the request. To set a role for an account, you need the accounts.roles--all:rw scope.

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token (accounts--all:rwaccounts.roles--all:rw)
      path Parameters
      account_id
      required
      string <uuid>

      Unique account ID or me

      Request Body schema: application/json
      name
      string <= 191 characters

      Account name (nick; first, second name; or both)

      default_product
      string
      Enum: "LiveChat" "Accounts"

      Available product name

      default_organization_id
      string <uuid> Nullable
      Default: null

      ID of default organization the account belongs to.

      avatar_url
      string <= 255 characters Nullable
      Default: null

      Account's avatar

      Responses

      Request samples

      Content type
      application/json
      {
      • "name": "John",
      • "email": "john@example.com",
      • "default_product": "Accounts",
      • "default_organization_id": "b2185556-634c-4ecf-b4c9-bcf8b65bc853",
      • "avatar_url": null,
      • "roles": [
        ]
      }

      Response samples

      Content type
      application/json
      {
      • "account_id": "496a94f2-cbbf-444e-a3cb-305b9f5f8cbb",
      • "name": "John",
      • "email": "john@example.com",
      • "email_verified": false,
      • "default_product": "Accounts",
      • "default_organization_id": "b2185556-634c-4ecf-b4c9-bcf8b65bc853",
      • "avatar_url": null,
      • "roles": [
        ],
      • "updated_at": "2019-09-03T10:53:04.000Z",
      • "created_at": "2019-09-03T10:53:04.000Z"
      }

      Delete an account

      Deletes an account for a given account_id. The ID can be replaced with me to delete the account that performs the request.

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token (accounts--my:rw)
      path Parameters
      account_id
      required
      string <uuid>

      Unique account ID or me

      Responses

      Response samples

      Content type
      application/json
      {
      • "error": "unauthorized",
      • "error_description": "The account is not authorized.",
      • "request_id": "5903c51b-89f0-41a9-a25d-4f39af100353"
      }

      Set account roles

      Set or delete roles for a given account_id. Set overwrites a role group in case of conflicts.

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token (accounts.roles--all:rw)
      path Parameters
      account_id
      required
      string <uuid>

      Unique account ID or me

      Request Body schema: application/json
      Array of objects or objects

      The list of role definitions that will be set for the account.

      Array of objects or objects

      The list of role definitions that will be deleted from the account.

      Responses

      Request samples

      Content type
      application/json
      {
      • "set_roles": [
        ],
      • "delete_roles": [
        ]
      }

      Response samples

      Content type
      application/json
      {
      • "account_id": "496a94f2-cbbf-444e-a3cb-305b9f5f8cbb",
      • "name": "John",
      • "email": "john@example.com",
      • "email_verified": false,
      • "default_product": "Accounts",
      • "default_organization_id": "b2185556-634c-4ecf-b4c9-bcf8b65bc853",
      • "avatar_url": null,
      • "roles": [
        ],
      • "updated_at": "2019-09-03T10:53:04.000Z",
      • "created_at": "2019-09-03T10:53:04.000Z"
      }

      Set a password

      This method sets a new password. A successful call revokes all session tokens. It's possible to set a password for other accounts only when they belong to a single organization.

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token (accounts.password--my:rw)
      path Parameters
      account_id
      required
      string <uuid>

      Unique account ID or me

      Request Body schema: application/json
      password
      required
      string [ 8 .. 255 ] characters

      Password for a given account

      Responses

      Request samples

      Content type
      application/json
      {
      • "password": "BG0SaleEBL"
      }

      Response samples

      Content type
      application/json
      {
      • "account_id": "496a94f2-cbbf-444e-a3cb-305b9f5f8cbb",
      • "name": "John",
      • "email": "john@example.com",
      • "email_verified": false,
      • "default_product": "Accounts",
      • "default_organization_id": "b2185556-634c-4ecf-b4c9-bcf8b65bc853",
      • "avatar_url": null,
      • "roles": [
        ],
      • "updated_at": "2019-09-03T10:53:04.000Z",
      • "created_at": "2019-09-03T10:53:04.000Z"
      }

      Roles

      List roles

      List the roles available for an organization. The result combines predefined and user-defined roles.

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token (accounts.roles--all:ro)

      Responses

      Response samples

      Content type
      application/json
      [
      • {
        }
      ]

      Get a role

      Get a single role for a given role_id. The role is returned with the scopes assigned to it.

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token (accounts.roles--all:ro)
      path Parameters
      role_id
      required
      string <uuid>

      Unique role ID

      Responses

      Response samples

      Content type
      application/json
      {
      • "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
      • "product": "Accounts",
      • "role": "administrator",
      • "type": "primary",
      • "predefined": true,
      • "scope": "accounts--all:rw,accounts.roles--all:ro"
      }

      Delete a role

      Delete a single role for a given role_id. Only the custom role can be deleted. All tokens related to a given role will be revoked.

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token (accounts.roles--all:rw)
      path Parameters
      role_id
      required
      string

      Unique role ID

      Responses

      Response samples

      Content type
      application/json
      {
      • "error": "unauthorized",
      • "error_description": "The account is not authorized.",
      • "request_id": "5903c51b-89f0-41a9-a25d-4f39af100353"
      }

      Sessions

      List sessions

      Returns all sessions for a given account ID. The account ID is obtained from an authorization grant.

      Authorizations:
      OAuth2 Bearer Token (sessions--my:ro)

      Responses

      Response samples

      Content type
      application/json
      [
      • {
        }
      ]

      Remove all sessions

      Removes all sessions for a given account ID. The account ID is obtained from an authorization grant. It's impossible to remove a session for other accounts. All access tokens related to the sessions will be revoked.

      Authorizations:
      OAuth2 Bearer Token (accounts--all:roaccounts.roles--all:ro)

      Responses

      Response samples

      Content type
      application/json
      {
      • "error": "unauthorized",
      • "error_description": "The account is not authorized.",
      • "request_id": "5903c51b-89f0-41a9-a25d-4f39af100353"
      }

      Remove a session

      Removes a specific session for a given account ID. The account ID is obtained from an authorization grant. It's impossible to remove a session for other accounts. All access tokens related to the sessions will be revoked.

      Authorizations:
      OAuth2 Bearer Token (sessions--my:rw)
      path Parameters
      session_id
      required
      string <uuid>

      Unique session ID

      Responses

      Response samples

      Content type
      application/json
      {
      • "error": "unauthorized",
      • "error_description": "The account is not authorized.",
      • "request_id": "5903c51b-89f0-41a9-a25d-4f39af100353"
      }

      Organizations

      List organizations

      Lists all organizations that an account belongs to, based on authorization.

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token

      Responses

      Response samples

      Content type
      application/json
      [
      • {
        }
      ]

      Create an organization

      Creates an organization and an account. Calling this endpoint won't result in email notifications. Alternatively, you can use Bearer/Basic authorization instead of creating a new account for an organization; it will create a new organization for the account associated with the token.

      Request Body schema: application/json
      email
      required
      string <email> <= 128 characters

      Account's email address

      password
      string [ 8 .. 255 ] characters

      Password for a given account

      object

      Organization groups accounts into a single unit. Each organization must contain at least one account and one owner. An account can be assigned to many organizations at once. The default organization is the first assigned to a given account.

      Responses

      Request samples

      Content type
      application/json
      {
      • "email": "john@example.com",
      • "password": "BG0SaleEBL",
      • "organization": {
        }
      }

      Response samples

      Content type
      application/json
      {
      • "account_id": "496a94f2-cbbf-444e-a3cb-305b9f5f8cbb",
      • "name": "John",
      • "email": "john@example.com",
      • "email_verified": false,
      • "default_product": "Accounts",
      • "default_organization_id": "b2185556-634c-4ecf-b4c9-bcf8b65bc853",
      • "avatar_url": null,
      • "roles": [
        ],
      • "updated_at": "2019-09-03T10:53:04.000Z",
      • "created_at": "2019-09-03T10:53:04.000Z",
      • "organization": {
        },
      • "access_token": "dal:eDqDuTRZoK03C3rzD2dcfA=="
      }

      Get an organization

      Returns a single organization for a given organization ID. The ID can be replaced with me to get the account that sends the request.

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token
      path Parameters
      organization_id
      required
      string <uuid>

      Unique account ID or me

      Responses

      Response samples

      Content type
      application/json
      {
      • "organization_id": "59aa5076-13c5-4ce5-b13a-07d33e838acf",
      • "name": "Organization Name",
      • "company": {
        }
      }

      Update an organization

      Updates an organization

      Authorizations:
      Personal Access TokenOAuth2 Bearer Token (organization--my:rw)
      path Parameters
      organization_id
      required
      string <uuid>

      Unique account ID or me

      Request Body schema: application/json
      name
      string <= 127 characters

      Organization name

      object

      Basic company information

      Responses

      Request samples

      Content type
      application/json
      {
      • "name": "Organization Name",
      • "company": {
        }
      }

      Response samples

      Content type
      application/json
      {
      • "organization_id": "59aa5076-13c5-4ce5-b13a-07d33e838acf",
      • "name": "Organization Name",
      • "company": {
        }
      }

      Tokens

      Get token details

      Some access tokens are paired with a refresh token. The access token can be provided via authorization or a query string.

      Authorizations:
      OAuth2 Bearer Token
      query Parameters
      code
      string
      Example: code=fra-a:vky95357S7KM1E4dXwv1DQ

      Responses

      Response samples

      Content type
      application/json
      {
      • "access_token": "fra-a:vky95357S7KM1E4dXwv1DQ",
      • "account_id": "28df1a50-84fa-490c-9615-5b77d507c393",
      • "expires_in": 432000,
      • "organization_id": "59aa5076-13c5-4ce5-b13a-07d33e838acf",
      • "refresh_token": "fra-a:0SEkeLZ2Qy2Nm2cg42xIyg",
      • "scope": "accounts--all:rc,accounts--all:ro",
      • "token_type": "Bearer"
      }