Xentral User API
User represents a Xentral account used to access other parts of the system.
OpenAPI Specification
openapi: 3.0.0
info:
title: Xentral Account User API
version: v0.1
description: Xentral is an ERP platform.
contact:
name: Xentral
url: https://xentral.com
email: api@xentral.com
servers:
- url: https://{xentralId}.xentral.biz
description: Your Xentral Instance
variables:
xentralId:
default: xentral
- url: https://{domain}
description: Xentral at a custom domain
variables:
domain:
default: xentral.com
security:
- BearerAuth: []
tags:
- name: User
description: User represents a Xentral account used to access other parts of the system.
paths:
/api/v1/users:
post:
tags:
- User
operationId: user.create
summary: Create user
description: Creates a new user using one of the available operations
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- username
- email
- password
properties:
username:
type: string
email:
type: string
password:
type: string
description:
type: string
color:
type: string
pattern: '[a-fA-F0-9]{6}'
example: ff0000
description: 'Hexadecimal color value in 6-digit format without the leading # character.'
locale:
type: string
enum:
- de_DE
- en_US
pattern: '[a-z]{2}_[A-Z]{2}'
example: de_DE
description: ISO 15897 locale which matches one of the available locale values.
examples:
user create:
value:
username: Test user name
email: test@example.com
password: '1234'
description: Test user description
color: ff0000
locale: de_DE
responses:
'201':
description: Resource successfully created response
headers:
Location:
schema:
type: string
example: https://example.xentral.biz/api/users/17
description: URI of the created resource
content:
text/html:
schema:
type: string
enum:
- ''
nullable: true
'400':
description: IETF RFC 9457 Problem API compliant response
content:
application/problem+json:
schema:
oneOf:
- type: object
additionalProperties: false
required:
- type
- title
- violations
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/request-validation
title:
type: string
minLength: 1
example: Request payload validation failed.
violations:
oneOf:
- type: array
items:
type: object
example:
username:
- This value should not be blank.
email:
- This value is not a valid email address.
description: This field will be a mirrored request payload with only invalid fields and values replaced by error messages.
- type: object
example:
_:
- This value should contain at most `9` elements.
description: This field will be a mirrored request payload with only invalid fields and values replaced by error messages.
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/generic-validation
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/conflict
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- items
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/conflictItems
title:
type: string
minLength: 1
items:
type: array
items:
type: object
additionalProperties: false
required:
- id
- title
- messages
properties:
id:
type: integer
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- scopes
properties:
type:
type: string
enum:
- https://developer.xentral.com/reference/problems#token-scopes
title:
type: string
minLength: 1
scopes:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/generic-validation
title:
type: string
minLength: 1
messages:
type: object
additionalProperties:
type: array
items:
type: string
'401':
description: Unable to authenticate the client
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message explaining why the request failed.
example: 'Missing required scopes: customer:create.'
example:
message: 'Missing required scopes: customer:create.'
text/html:
schema:
type: string
example: Unauthorized
'403':
description: Unable to authorize the client
'415':
description: Resource representation send in the request is not supported.
'429':
description: Too many API calls made.
get:
deprecated: true
tags:
- User
operationId: user.list
summary: List users
description: Returns a collection with all users.
parameters:
- name: filter
in: query
description: V1 filter format (used with application/json Accept header)
style: deepObject
schema:
type: object
additionalProperties: false
properties:
ids:
type: array
items:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
username:
type: string
description:
type: string
color:
type: string
pattern: ^[a-fA-F0-9]{6}$
isActive:
type: boolean
email:
type: string
- in: query
name: page
required: false
style: deepObject
schema:
type: object
additionalProperties: false
required:
- number
- size
properties:
number:
type: string
pattern: \d+
description: Page number should be an integer greater than or equal to 1
size:
type: string
pattern: \d+
description: Page size should usually be an integer between 10 and 50.
- name: order
in: query
style: deepObject
schema:
type: array
items:
type: object
additionalProperties: false
properties:
field:
type: string
enum:
- id
- username
- isActive
- createdAt
dir:
type: string
enum:
- asc
- desc
responses:
'200':
description: Operation completed successfully.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- data
- extra
properties:
data:
description: A list of users
type: array
items:
description: User resource.
type: object
additionalProperties: false
required:
- id
- username
- description
- createdAt
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
globalUserId:
description: Nullable UUID identifier of the resource.
type: string
pattern: ^$|^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$
example: a00fd11e-3a67-433b-83c0-4e815fd4a0e1
nullable: true
username:
description: The name of the user
type: string
example: Benedikt
createdAt:
description: The date the user was created
type: string
format: date-time
example: '2023-08-13T14:45:36+02:00'
description:
x-description-ignore: true
type: string
nullable: true
example: This is the user description.
color:
description: 'An optional hex value without the #, representing the avatar color'
type: string
nullable: true
example: ff0000
isActive:
description: A boolean value indicating if the user is active and can log in
type: boolean
example: true
locale:
description: A ISO-639-1 formatted string indicating the language the user will use
type: string
example: de_DE
isAdmin:
description: A boolean value indicating if the user is an admin
type: boolean
example: false
email:
x-description-ignore: true
type: string
nullable: true
example: example@xentral.com
emailVerifiedAt:
description: The date where the user verified his email address
type: string
format: date-time
nullable: true
example: '2023-08-14T14:45:36+02:00'
mfa:
description: Auth Platform MFA state
type: boolean
nullable: true
example: false
contactId:
description: The ID of the contact/address associated with this user
type: string
nullable: true
example: '123'
example:
id: '12'
globalUserId: f7b3b3b3-7b3b-4b3b-8b3b-3b3b3b3b3b3b
username: Bene
createdAt: '2023-08-13T14:45:36+02:00'
description: This is the user description.
color: ff0000
isActive: true
locale: de_DE
isAdmin: true
email: ceo@example.com
emailVerifiedAt: '2023-08-14T14:45:36+02:00'
contactId: '123'
extra:
type: object
required:
- totalCount
- page
additionalProperties: false
x-description-ignore: true
properties:
totalCount:
description: the total count of all items
type: integer
example: 1
page:
description: The pagination object containing the current page number and size
type: object
required:
- number
- size
additionalProperties: false
properties:
number:
description: The current page number
type: integer
example: 1
size:
description: The size of the pages
type: integer
example: 10
example:
number: 1
size: 10
example:
totalCount: 1
page:
number: 1
size: 10
'401':
description: Unable to authenticate the client
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message explaining why the request failed.
example: 'Missing required scopes: customer:create.'
example:
message: 'Missing required scopes: customer:create.'
text/html:
schema:
type: string
example: Unauthorized
'403':
description: Unable to authorize the client
'406':
description: Requested resource representation does not exist.
'429':
description: Too many API calls made.
/api/v2/users:
get:
tags:
- User
operationId: user.list.v2
summary: List users V2
description: Returns a collection with all users.
parameters:
- name: filter
in: query
style: deepObject
schema:
type: array
items:
type: object
additionalProperties: false
properties:
key:
type: string
enum:
- search
- id
- username
- description
- isActive
- isAdmin
- mfa
- email
op:
type: string
enum:
- equals
- notEquals
- in
- notIn
- exactlyIn
- allIn
- allNotIn
- contains
- notContains
- startsWith
- endsWith
- greaterThan
- lessThan
- is
- lessThanOrEquals
- greaterThanOrEquals
value:
oneOf:
- type: string
description: Used for the operations 'equals', 'notEquals', 'contains', 'notContains', 'startsWith', 'endsWith' and 'is'.
title: String
- type: array
description: Used for the operations 'in', 'notIn', 'exactlyIn', 'allIn' and 'allNotIn'.
title: Array
items:
type: string
- in: query
name: page
required: false
style: deepObject
schema:
type: object
additionalProperties: false
required:
- number
- size
properties:
number:
type: string
pattern: \d+
description: Page number should be an integer greater than or equal to 1
size:
type: string
pattern: \d+
description: Page size should usually be an integer between 10 and 50.
- name: order
in: query
style: deepObject
schema:
type: array
items:
type: object
additionalProperties: false
properties:
field:
type: string
enum:
- id
- username
- isActive
- isAdmin
- mfa
- createdAt
dir:
type: string
enum:
- asc
- desc
responses:
'200':
description: Operation completed successfully.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- data
- extra
properties:
data:
description: A list of users
type: array
items:
description: User resource.
type: object
additionalProperties: false
required:
- id
- username
- description
- createdAt
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
globalUserId:
description: Nullable UUID identifier of the resource.
type: string
pattern: ^$|^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$
example: a00fd11e-3a67-433b-83c0-4e815fd4a0e1
nullable: true
username:
description: The name of the user
type: string
example: Benedikt
createdAt:
description: The date the user was created
type: string
format: date-time
example: '2023-08-13T14:45:36+02:00'
description:
x-description-ignore: true
type: string
nullable: true
example: This is the user description.
color:
description: 'An optional hex value without the #, representing the avatar color'
type: string
nullable: true
example: ff0000
isActive:
description: A boolean value indicating if the user is active and can log in
type: boolean
example: true
locale:
description: A ISO-639-1 formatted string indicating the language the user will use
type: string
example: de_DE
isAdmin:
description: A boolean value indicating if the user is an admin
type: boolean
example: false
email:
x-description-ignore: true
type: string
nullable: true
example: example@xentral.com
emailVerifiedAt:
description: The date where the user verified his email address
type: string
format: date-time
nullable: true
example: '2023-08-14T14:45:36+02:00'
mfa:
description: Auth Platform MFA state
type: boolean
nullable: true
example: false
contactId:
description: The ID of the contact/address associated with this user
type: string
nullable: true
example: '123'
example:
id: '12'
globalUserId: f7b3b3b3-7b3b-4b3b-8b3b-3b3b3b3b3b3b
username: Bene
createdAt: '2023-08-13T14:45:36+02:00'
description: This is the user description.
color: ff0000
isActive: true
locale: de_DE
isAdmin: true
email: ceo@example.com
emailVerifiedAt: '2023-08-14T14:45:36+02:00'
contactId: '123'
extra:
type: object
required:
- totalCount
- page
additionalProperties: false
x-description-ignore: true
properties:
totalCount:
description: the total count of all items
type: integer
example: 1
page:
description: The pagination object containing the current page number and size
type: object
required:
- number
- size
additionalProperties: false
properties:
number:
description: The current page number
type: integer
example: 1
size:
description: The size of the pages
type: integer
example: 10
example:
number: 1
size: 10
example:
totalCount: 1
page:
number: 1
size: 10
'401':
description: Unable to authenticate the client
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message explaining why the request failed.
example: 'Missing required scopes: customer:create.'
example:
message: 'Missing required scopes: customer:create.'
text/html:
schema:
type: string
example: Unauthorized
'403':
description: Unable to authorize the client
'429':
description: Too many API calls made.
/api/v1/users/{id}:
get:
tags:
- User
operationId: user.view
summary: View user
description: Returns details of a single user
parameters:
- in: path
name: id
required: true
description: The resource's identifier.
schema:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
responses:
'200':
description: A single user resource.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- data
properties:
data:
description: User resource.
type: object
additionalProperties: false
required:
- id
- username
- description
- createdAt
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
globalUserId:
description: Nullable UUID identifier of the resource.
type: string
pattern: ^$|^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$
example: a00fd11e-3a67-433b-83c0-4e815fd4a0e1
nullable: true
username:
description: The name of the user
type: string
example: Benedikt
createdAt:
description: The date the user was created
type: string
format: date-time
example: '2023-08-13T14:45:36+02:00'
description:
x-description-ignore: true
type: string
nullable: true
example: This is the user description.
color:
description: 'An optional hex value without the #, representing the avatar color'
type: string
nullable: true
example: ff0000
isActive:
description: A boolean value indicating if the user is active and can log in
type: boolean
example: true
locale:
description: A ISO-639-1 formatted string indicating the language the user will use
type: string
example: de_DE
isAdmin:
description: A boolean value indicating if the user is an admin
type: boolean
example: false
email:
x-description-ignore: true
type: string
nullable: true
example: example@xentral.com
emailVerifiedAt:
description: The date where the user verified his email address
type: string
format: date-time
nullable: true
example: '2023-08-14T14:45:36+02:00'
mfa:
description: Auth Platform MFA state
type: boolean
nullable: true
example: false
contactId:
description: The ID of the contact/address associated with this user
type: string
nullable: true
example: '123'
example:
id: '12'
globalUserId: f7b3b3b3-7b3b-4b3b-8b3b-3b3b3b3b3b3b
username: Bene
createdAt: '2023-08-13T14:45:36+02:00'
description: This is the user description.
color: ff0000
isActive: true
locale: de_DE
isAdmin: true
email: ceo@example.com
emailVerifiedAt: '2023-08-14T14:45:36+02:00'
contactId: '123'
application/vnd.xentral.user-permissions+json:
schema:
type: object
additionalProperties: false
required:
- data
properties:
data:
description: An object containing all the users permissions.
type: object
additionalProperties: false
required:
- id
- username
- description
- createdAt
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
globalUserId:
description: Nullable UUID identifier of the resource.
type: string
pattern: ^$|^[0-9a-fA-F]{8}\b-[0-9
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xentral/refs/heads/main/openapi/xentral-user-api-openapi.yml