openapi: 3.0.0
info:
title: Customer Accounts API
description: >-
Customer Accounts API is responsible for the authentication and authorization processes of customers in LiveChat.
version: 2.0.0
servers:
- url: "https://accounts.livechat.com/v2/customer"
description: Main production server URL
paths:
/info:
get:
summary: Get token details
description: >-
Retrieve information about an access token. You can provide the token via authorization or a query string.
security:
- OAuth2 Bearer Token: []
parameters:
- in: query
name: code
schema:
type: string
example: "fra-a:vky95357S7KM1E4dXwv1DQ"
tags:
- Tokens
responses:
"200":
description: "OK: Returns token details."
content:
application/json:
schema:
description: OAuth 2 `Bearer` token
type: object
properties:
access_token:
type: string
description: Access token value
example: "fra-a:vky95357S7KM1E4dXwv1DQ"
client_id:
type: string
format: hex
description: Client ID for which the token was issued
example: c6e4f62e2a2dab12531235b12c5a2a6b
entity_id:
type: string
format: uuid
description: Entity ID for which the token was issued
example: 3aa138c1-c137-41c6-6b26-cface5857378
expires_in:
type: integer
format: uint64
description: Access token lifetime (in seconds)
example: 28800
organization_id:
type: string
format: uuid
description: Organization ID for which the token was issued
example: 390e44e6-f1e6-0368c-z6ddb-74g14508c2e
token_type:
type: string
description: Access token type
example: Bearer
"401":
description: Unauthorized, missing or invalid authorization
content:
application/json:
schema: &ref_0
description: Default error object
type: object
properties:
oauth_exception:
type: string
example: invalid_request
enum:
- bad_request
- invalid_request
- unauthorized_client
- access_denied
- server_error
- temporarily_unavailable
- unsupported_grant_type
- invalid_grant
- invalid_client
- forbidden
- conflict
- resource_not_found
exception_description:
type: string
example: >-
The request is missing a required parameter, includes an invalid parameter value,
includes a parameter more than once, or is otherwise malformed.
"500":
description: Server Error
/token:
post:
summary: Create a token
description: Creates a new customer access token.
security:
- {}
- Cookie Auth: []
- OAuth2 Agent Bearer Token: []
tags:
- Tokens
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
grant_type:
type: string
enum:
- agent_token
- cookie
- identity_token
example: agent_token
description: Grant type
client_id:
type: string
format: hex
description: Client ID for which the token is being issued
example: c6e4f62e2a2dab12531235b12c5a2a6b
redirect_uri:
type: string
format: url
example: https://my-application.com
description: >-
Redirect URI; it can be used and is required only for `grant_type=cookie`, default: the value of the `Origin` header.
organization_id:
type: string
format: uuid
description: Organization ID for which the token is being issued, required only if `grant_type=cookie`
example: 390e44e6-f1e6-0368c-z6ddb-74g14508c2e
entity_id:
type: string
format: uuid
description: >-
Entity ID for which the token is being issued; the entity (customer) should already exist;
it can be used only for `grant_type=agent_token`
example: 3aa138c1-c137-41c6-6b26-cface5857378
expires_in:
type: integer
format: uint64
description: Access token lifetime (in seconds)
example: 28800
code:
type: string
description: >-
Code is an identity transfer token; it can be used only for `grant_type=identity_token`
example: fra-a:vky95357S7KM1E4dXwv1DV
code_verifier:
type: string
description: >-
Code verifier, as in OAuth2 PKCE flow; it can be used only for `grant_type=identity_token`
example: y4jtqb2noru3vc23pefs
required:
- grant_type
- client_id
responses:
"200":
description: "OK: Returns token details."
headers:
Set-Cookie:
schema:
type: string
description: Customer ID cookie, returned only if `grant_type=cookie`
example: >-
__lc_cid=3aa138c1-c137-41c6-6b26-cface5857378; Path=/customer; Domain=accounts.livechat.com;
Expires=Sun, 18 Jun 2023 12:26:02 GMT; Max-Age=63072000; HttpOnly; Secure; SameSite=None
"\0Set-Cookie":
schema:
type: string
description: Customer Secure Token cookie, returned only if `grant_type=cookie`
example: >-
__lc_cst=87b9d0222e63e349da85535d07c81e1e1fb938de41f4e16e1d9ba5965f25db4aeea46b39d0fb;
Path=/customer; Domain=accounts.livechat.com; Expires=Sun, 18 Jun 2023 12:26:02 GMT;
Max-Age=63072000; HttpOnly; Secure; SameSite=None
content:
application/json:
schema:
description: OAuth 2 `Bearer` token
type: object
properties:
access_token:
type: string
description: Access token value
example: "fra-a:vky95357S7KM1E4dXwv1DQ"
client_id:
type: string
format: hex
description: Client ID for which the token was issued
example: c6e4f62e2a2dab12531235b12c5a2a6b
entity_id:
type: string
format: uuid
description: Entity ID for which the token was issued
example: 3aa138c1-c137-41c6-6b26-cface5857378
expires_in:
type: integer
format: uint64
description: Access token lifetime (in seconds)
example: 28800
token_type:
type: string
description: Access token type
example: Bearer
organization_id:
type: string
format: uuid
description: Organization ID for which the token was issued
example: 390e44e6-f1e6-0368c-z6ddb-74g14508c2e
"401":
description: Unauthorized, missing or invalid authorization
content:
application/json:
schema: *ref_0
"500":
description: Server Error
delete:
summary: Revoke token
description: >-
Revoke a token provided via authorization.
security:
- OAuth2 Bearer Token: []
tags:
- Tokens
responses:
"200":
description: "OK: Returns no content."
"401":
description: Unauthorized, missing or invalid authorization
content:
application/json:
schema: *ref_0
"500":
description: Server Error
/identity_transfer:
post:
summary: Create an identity transfer token
description: Creates a new identity transfer token, which can be exchanged for a customer access token.
security:
- OAuth2 Bearer Token: []
- OAuth2 Agent Bearer Token: []
tags:
- Tokens
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
bearer_type:
type: string
enum:
- agent
- customer
example: agent
description: Authorization token type; `agent` for OAuth2 Agent Bearer Token and `customer` for OAuth2 Bearer Token
customer_id:
type: string
format: uuid
description: >-
Customer ID for which the identity transfer token is being issued; the customer should already exist;
required only if `bearer_type=agent`
example: 3aa138c1-c137-41c6-6b26-cface5857378
client_id:
type: string
format: hex
description: Client ID for which the token is being issued
example: c6e4f62e2a2dab12531235b12c5a2a6b
code_challenge:
type: string
description: Code challenge, as in OAuth2 PKCE flow.
example: 9_r7xBQQ8RJ3NOr0AMDBqASrf5ZT41PG1qjuLEYDs-c
required:
- bearer_type
- client_id
responses:
"200":
description: "OK: returns identity transfer token details."
content:
application/json:
schema:
description: Identity transfer token
type: object
properties:
identity_transfer_token:
type: string
description: Identity transfer token value
example: fra-a:vky95357S7KM1E4dXwv1DV
expires_in:
type: integer
format: uint64
description: Identity transfer token lifetime (in seconds)
example: 3600
"401":
description: Unauthorized, missing or invalid authorization
content:
application/json:
schema: *ref_0
"500":
description: Server Error
/{organization_id}/{group_id}/token/:
post:
summary: Create a group token
description: Creates a new customer access token for a different group within the same organization. Use this token to separate customer identity across groups within one organization, click here for more information.
security:
- {}
- Cookie Auth: []
- OAuth2 Agent Bearer Token: []
tags:
- Tokens
parameters:
- in: path
name: organization_id
schema:
type: string
format: uuid
required: true
description: Unique organization identifier.
- in: path
name: group_id
schema:
type: string
format: uuid
required: true
description: Unique group identifier.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
grant_type:
type: string
enum:
- agent_token
- cookie
- identity_token
example: agent_token
description: Grant type
client_id:
type: string
format: hex
description: Client ID for which the token is being issued
example: c6e4f62e2a2dab12531235b12c5a2a6b
redirect_uri:
type: string
format: url
example: https://my-application.com
description: >-
Redirect URI; default: the value of the `Origin` header; it can be used only for `grant_type=cookie`
license_id:
type: integer
format: uint64
description: License ID for which the token is being issued, required only if `grant_type=cookie`
example: 2491303
entity_id:
type: string
format: uuid
description: >-
Entity ID for which the token is being issued; the entity (customer) should already exist;
it can be used only for `grant_type=agent_token`
example: 3aa138c1-c137-41c6-6b26-cface5857378
expires_in:
type: integer
format: uint64
description: Access token lifetime (in seconds)
example: 28800
code:
type: string
description: >-
Code is an identity transfer token; it can be used only for `grant_type=identity_token`
example: fra-a:vky95357S7KM1E4dXwv1DV
code_verifier:
type: string
description: >-
Code verifier, as in OAuth2 PKCE flow; it can be used only for `grant_type=identity_token`
example: y4jtqb2noru3vc23pefs
required:
- grant_type
- client_id
responses:
"200":
description: "OK: Returns token details."
headers:
Set-Cookie:
schema:
type: string
description: Customer ID cookie, returned only if `grant_type=cookie`
example: >-
__lc_cid=3aa138c1-c137-41c6-6b26-cface5857378; Path=/customer; Domain=accounts.livechat.com;
Expires=Sun, 18 Jun 2023 12:26:02 GMT; Max-Age=63072000; HttpOnly; Secure; SameSite=None
"\0Set-Cookie":
schema:
type: string
description: Customer Secure Token cookie, returned only if `grant_type=cookie`
example: >-
__lc_cst=87b9d0222e63e349da85535d07c81e1e1fb938de41f4e16e1d9ba5965f25db4aeea46b39d0fb;
Path=/customer; Domain=accounts.livechat.com; Expires=Sun, 18 Jun 2023 12:26:02 GMT;
Max-Age=63072000; HttpOnly; Secure; SameSite=None
content:
application/json:
schema:
description: OAuth 2 `Bearer` token
type: object
properties:
access_token:
type: string
description: Access token value
example: "fra-a:vky95357S7KM1E4dXwv1DQ"
client_id:
type: string
format: hex
description: Client ID for which the token was issued
example: c6e4f62e2a2dab12531235b12c5a2a6b
entity_id:
type: string
format: uuid
description: Entity ID for which the token was issued
example: 3aa138c1-c137-41c6-6b26-cface5857378
expires_in:
type: integer
format: uint64
description: Access token lifetime (in seconds)
example: 28800
token_type:
type: string
description: Access token type
example: Bearer
"401":
description: Unauthorized, missing or invalid authorization
content:
application/json:
schema: &ref_0
description: Default error object
type: object
properties:
oauth_exception:
type: string
example: invalid_request
enum:
- bad_request
- invalid_request
- unauthorized_client
- access_denied
- server_error
- temporarily_unavailable
- unsupported_grant_type
- invalid_grant
- invalid_client
- forbidden
- conflict
- resource_not_found
exception_description:
type: string
example: >-
The request is missing a required parameter, includes an invalid parameter value,
includes a parameter more than once, or is otherwise malformed.
"500":
description: Server Error
components:
schemas: {}
securitySchemes:
OAuth2 Bearer Token:
description: This API uses OAuth2 tokens.
type: oauth2
flows:
implicit:
authorizationUrl: "https://accounts.livechat.com/v2/customer"
OAuth2 Agent Bearer Token:
description: >-
This API uses OAuth2 for agents with the Implicit grant flow. Learn
about the implicit grant flow.
type: oauth2
flows:
implicit:
authorizationUrl: "https://accounts.livechat.com"
authorizationCode:
authorizationUrl: "https://accounts.livechat.com"
tokenUrl: "https://accounts.livechat.com/token"
Cookie Auth:
type: apiKey
in: cookie
name:
- __lc_cid
- __lc_cst