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.
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: |
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:
accounts--all:ro
accounts.roles--all:ro
) Responses
Response samples
- 200
- 401
- 403
- 500
[- {
- "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": [
- {
- "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
- "product": "Accounts",
- "role": "administrator",
- "type": "primary",
- "predefined": true
}
], - "updated_at": "2019-09-03T10:53:04.000Z",
- "created_at": "2019-09-03T10:53:04.000Z"
}
]
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:
accounts--all:rw
accounts--all:rc
accounts.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 | |
password | string [ 8 .. 255 ] characters Password for a given account |
Responses
Request samples
- Payload
{- "name": "John",
- "email": { },
- "default_product": "Accounts",
- "default_organization_id": "b2185556-634c-4ecf-b4c9-bcf8b65bc853",
- "avatar_url": null,
- "roles": [
- {
- "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
- "product": "Accounts",
- "role": "administrator"
}
], - "password": "BG0SaleEBL"
}
Response samples
- 200
- 201
- 400
- 401
- 403
- 409
- 422
- 500
{- "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": [
- {
- "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
- "product": "Accounts",
- "role": "administrator",
- "type": "primary",
- "predefined": true
}
], - "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:
accounts--my:ro
accounts.roles--all:ro
) path Parameters
account_id required | string <uuid> Unique account ID or |
Responses
Response samples
- 200
- 401
- 403
- 404
- 422
- 500
{- "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": [
- {
- "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
- "product": "Accounts",
- "role": "administrator",
- "type": "primary",
- "predefined": true
}
], - "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:
accounts--all:rw
accounts.roles--all:rw
) path Parameters
account_id required | string <uuid> Unique account ID or |
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
- Payload
{- "name": "John",
- "email": "john@example.com",
- "default_product": "Accounts",
- "default_organization_id": "b2185556-634c-4ecf-b4c9-bcf8b65bc853",
- "avatar_url": null,
- "roles": [
- {
- "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
- "product": "Accounts",
- "role": "administrator"
}
]
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 422
- 500
{- "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": [
- {
- "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
- "product": "Accounts",
- "role": "administrator",
- "type": "primary",
- "predefined": true
}
], - "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:
accounts--my:rw
) path Parameters
account_id required | string <uuid> Unique account ID or |
Responses
Response samples
- 401
- 403
- 404
- 422
- 500
{- "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:
accounts.roles--all:rw
) path Parameters
account_id required | string <uuid> Unique account ID or |
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
- Payload
{- "set_roles": [
- {
- "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
- "product": "Accounts",
- "role": "administrator"
}
], - "delete_roles": [
- {
- "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
- "product": "Accounts",
- "role": "administrator"
}
]
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 422
- 500
{- "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": [
- {
- "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
- "product": "Accounts",
- "role": "administrator",
- "type": "primary",
- "predefined": true
}
], - "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:
accounts.password--my:rw
) path Parameters
account_id required | string <uuid> Unique account ID or |
Request Body schema: application/json
password required | string [ 8 .. 255 ] characters Password for a given account |
Responses
Request samples
- Payload
{- "password": "BG0SaleEBL"
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 409
- 422
- 500
{- "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": [
- {
- "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
- "product": "Accounts",
- "role": "administrator",
- "type": "primary",
- "predefined": true
}
], - "updated_at": "2019-09-03T10:53:04.000Z",
- "created_at": "2019-09-03T10:53:04.000Z"
}
List roles
List the roles available for an organization. The result combines predefined and user-defined roles.
Authorizations:
accounts.roles--all:ro
) Responses
Response samples
- 200
- 401
- 403
- 500
[- {
- "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
- "product": "Accounts",
- "role": "administrator",
- "type": "primary",
- "predefined": true
}
]
Get a role
Get a single role for a given role_id
. The role is returned with the scopes assigned to it.
Authorizations:
accounts.roles--all:ro
) path Parameters
role_id required | string <uuid> Unique role ID |
Responses
Response samples
- 200
- 401
- 403
- 404
- 422
- 500
{- "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:
accounts.roles--all:rw
) path Parameters
role_id required | string Unique role ID |
Responses
Response samples
- 401
- 403
- 404
- 422
- 500
{- "error": "unauthorized",
- "error_description": "The account is not authorized.",
- "request_id": "5903c51b-89f0-41a9-a25d-4f39af100353"
}
List sessions
Returns all sessions for a given account ID. The account ID is obtained from an authorization grant.
Authorizations:
sessions--my:ro
) Responses
Response samples
- 200
- 401
- 403
- 500
[- {
- "account_id": "28df1a50-84fa-490c-9615-5b77d507c393",
- "session_id": "bfeeb033-bc8e-467f-982d-22dcef274fa1",
- "current": true,
- "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:69.0) Gecko/20100101 Firefox/69.0",
- "identity_source": "credentials",
- "ip": "194.181.146.158",
- "applications": [
- {
- "name": "LiveChat Application",
- "client_id": "238ac4c3c3628880aca289c6d700d2c5",
- "session_id": "bfeeb033-bc8e-467f-982d-22dcef274fa1"
}
]
}
]
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:
accounts--all:ro
accounts.roles--all:ro
) Responses
Response samples
- 401
- 403
- 500
{- "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:
sessions--my:rw
) path Parameters
session_id required | string <uuid> Unique session ID |
Responses
Response samples
- 401
- 403
- 404
- 500
{- "error": "unauthorized",
- "error_description": "The account is not authorized.",
- "request_id": "5903c51b-89f0-41a9-a25d-4f39af100353"
}
List organizations
Lists all organizations that an account belongs to, based on authorization.
Authorizations:
Responses
Response samples
- 200
- 401
- 500
[- {
- "organization_id": "59aa5076-13c5-4ce5-b13a-07d33e838acf",
- "name": "Organization Name",
- "company": {
- "phone": "+48 123 456 789",
- "website": "example.com"
}
}
]
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
- Payload
{- "email": "john@example.com",
- "password": "BG0SaleEBL",
- "organization": {
- "name": "Organization Name",
- "company": {
- "phone": "+48 123 456 789",
- "website": "example.com"
}
}
}
Response samples
- 200
- 400
- 409
- 422
- 500
{- "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": [
- {
- "role_id": "728b99be-848c-11ea-9b91-005056a007e9",
- "product": "Accounts",
- "role": "administrator",
- "type": "primary",
- "predefined": true
}
], - "updated_at": "2019-09-03T10:53:04.000Z",
- "created_at": "2019-09-03T10:53:04.000Z",
- "organization": {
- "organization_id": "59aa5076-13c5-4ce5-b13a-07d33e838acf",
- "name": "Organization Name",
- "company": {
- "phone": "+48 123 456 789",
- "website": "example.com"
}
}, - "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:
path Parameters
organization_id required | string <uuid> Unique account ID or |
Responses
Response samples
- 200
- 401
- 404
- 500
{- "organization_id": "59aa5076-13c5-4ce5-b13a-07d33e838acf",
- "name": "Organization Name",
- "company": {
- "phone": "+48 123 456 789",
- "website": "example.com"
}
}
Update an organization
Updates an organization
Authorizations:
organization--my:rw
) path Parameters
organization_id required | string <uuid> Unique account ID or |
Request Body schema: application/json
name | string <= 127 characters Organization name |
object Basic company information |
Responses
Request samples
- Payload
{- "name": "Organization Name",
- "company": {
- "phone": "+48 123 456 789",
- "website": "example.com"
}
}
Response samples
- 200
- 401
- 403
- 404
- 422
- 500
{- "organization_id": "59aa5076-13c5-4ce5-b13a-07d33e838acf",
- "name": "Organization Name",
- "company": {
- "phone": "+48 123 456 789",
- "website": "example.com"
}
}
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:
query Parameters
code | string Example: code=fra-a:vky95357S7KM1E4dXwv1DQ |
Responses
Response samples
- 200
- 422
{- "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"
}