# Create User / Create Machine User
## OpenAPI Specification
```yaml
openapi: 3.0.1
info:
title: ''
description: ''
version: 1.0.0
paths:
/be/v1/users:
post:
summary: Create User / Create Machine User
deprecated: false
description: >-
This endpoint creates either a machine account to integrate the ROCKIT
Edge Backend API into existing automated workflows or a user account. By
calling this endpoint to create a user account, ROCKITPLAY sends an
invitation email to the specified address. By confirming the email
address the account will be enabled.
To create a machine account, use the following body schema:
- username
- label
- roles
To create an user account, use the following body schema:
- username
- title (optional)
- email
- firstname
- surname
- roles
### Required Permissions
`users.create`
See [Roles](https://edge.api.cloud.rockitplay.com/roles-3618377f0.md)
for more details.
tags:
- ROCKIT Edge - Backend API/Account Management
parameters:
- name: Authorization
in: header
description: >-
Use the access token obtained from [`POST
/be/v1/login`](https://edge.api.cloud.rockitplay.com/user-login-org-11611254e0.md)
or [`POST
/be/v1/refresh`](https://edge.api.cloud.rockitplay.com/refresh-11630082e0.md)
as Bearer token.
Mutually excluded with `x-rockit-api-key`.
required: true
example: Bearer {{_edge_org_admin_access_token}}
schema:
type: string
- name: x-rockit-orgname
in: header
description: >
Unique and immutable organization identifier obtained from the
ROCKIT Edge administrator.
Requires `x-rockit-tenant`,
`x-rockit-username` and `x-rockit-api-key`.
required: true
example: '{{EDGE_ORG_NAME}}'
schema:
type: string
- name: x-rockit-username
in: header
description: >
Unique and immutable username which is associated with the apikey.
Requires `x-rockit-tenant`, `x-rockit-orgname` and
`x-rockit-api-key`.
required: true
example: adminPrincipal
schema:
type: string
- name: x-rockit-api-key
in: header
description: >-
Unique and immutable apikey which is associated with an machine
user.
Mutually excluded with `Authorization` header. Requires
`x-rockit-tenant`, `x-rockit-username` and `x-rockit-orgname`.
required: true
example: '{{_adminPrincipal_apiKey}}'
schema:
type: string
- name: x-rockit-tenant
in: header
description: >
Unique and immutable tenancy identifier obtained from the ROCKIT
Edge administrator.
Requires `x-rockit-username`,
`x-rockit-orgname` and `x-rockit-api-key`.
required: false
example: '{{EDGE_TENANT_NAME}}'
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: 'Unique and immutable identifier of the user account. '
pattern: /^[A-Za-z0-9_]{2,50}$/
label:
type: string
description: An explanatory label describing the machine account purpose.
title:
type: string
description: Title of the user. Optional parameter.
email:
type: string
description: Email adress of the user is required for non-machine user.
firstname:
type: string
description: Firstname of the user.
surname:
type: string
description: Surname of the user.
roles:
type: array
items:
type: string
description: >-
Array of _Roles_ which the machine account should be
associated with.
verifyEmail:
type: boolean
description: >-
If set to false the email verification process is skipped
and the initial password is returned. The account is enabled
immediately.
x-apidog-orders:
- username
- label
- title
- email
- firstname
- surname
- roles
- verifyEmail
required:
- username
- title
- roles
x-apidog-ignore-properties: []
example:
username: exampleUser
title: Dr.
email: Cheyenne.Smitham54@hotmail.com
firstname: Roscoe
surname: Caroline Murray
roles:
- Administrators
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: >-
Indicates that the machine account was created
successfully.
message:
type: string
description: >-
Confirms the creation of the account (e.g., "machine
account created").
apiKey:
type: string
description: >-
Returns the generated API key for the new machine account,
which is used for authenticating subsequent requests.
required:
- status
- message
- apiKey
x-apidog-orders:
- status
- message
- apiKey
x-apidog-ignore-properties: []
examples:
'1':
summary: Success
value:
status: success
message: user account created
password: PO.sNP@g
'2':
summary: Unautharized
value:
status: string
error: string
message: string
headers: {}
x-apidog-name: Success
'400':
description: ''
content:
application/json:
schema:
title: ''
type: object
properties:
status:
type: string
description: >-
Reflects that the creation failed due to one or more
invalid or missing parameters in the request.
error:
type: string
description: Contains an error identifier. (e.g., "invalid-param")
message:
type: string
description: >-
Explains the nature of the invalid input (for example,
"name invalid").
detail:
type: string
description: >-
Offers further context on the error. (e.g., expected
pattern for the organization name)
x-apidog-orders:
- 01JQNGFHADGCY8163ZKVCDFMTS
required:
- status
- error
- message
- detail
x-apidog-refs:
01JQNGFHADGCY8163ZKVCDFMTS:
$ref: '#/components/schemas/Invalid%20Param'
x-apidog-ignore-properties:
- status
- error
- message
- detail
headers: {}
x-apidog-name: Invalid Param
'401':
description: ''
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: >-
Indicates that the organization creation request was
rejected because of authentication problems.
error:
type: string
description: Contains an error identifier. (e.g."unauthorized")
message:
type: string
description: >-
Provides details such as "invalid token" to help diagnose
the failure.
x-apidog-orders:
- 01JQNGEGCHBQ9G4XATHJ9S1VKC
required:
- status
- error
- message
x-apidog-refs:
01JQNGEGCHBQ9G4XATHJ9S1VKC:
$ref: '#/components/schemas/unauthorized'
x-apidog-ignore-properties:
- status
- error
- message
headers: {}
x-apidog-name: Unauthorized
'409':
description: ''
content:
application/json:
schema:
title: ''
type: object
properties:
status:
type: string
description: >-
Indicates that the request failed because an organization
with the same identifier already exists or is protected.
error:
type: string
description: Contains an error identifier. (e.g., "item exists")
message:
type: string
description: >-
States that the organization cannot be created due to a
conflict.
detail:
type: string
description: Provides additional context.
x-apidog-orders:
- 01JQNGM445T7CTCVTRWREBG8PD
required:
- status
- error
- message
- detail
x-apidog-refs:
01JQNGM445T7CTCVTRWREBG8PD:
$ref: '#/components/schemas/Item-exists'
x-apidog-ignore-properties:
- status
- error
- message
- detail
headers: {}
x-apidog-name: Item exists
security: []
x-apidog-folder: ROCKIT Edge - Backend API/Account Management
x-apidog-status: released
x-run-in-apidog: https://app.apidog.com/web/project/732774/apis/api-16603181-run
components:
schemas:
unauthorized:
type: object
properties:
status:
type: string
description: >-
Indicates that the organization creation request was rejected
because of authentication problems.
error:
type: string
description: Contains an error identifier. (e.g."unauthorized")
message:
type: string
description: >-
Provides details such as "invalid token" to help diagnose the
failure.
required:
- status
- error
- message
x-apidog-orders:
- status
- error
- message
x-apidog-ignore-properties: []
x-apidog-folder: ''
Invalid Param:
type: object
properties:
status:
type: string
description: >-
Reflects that the creation failed due to one or more invalid or
missing parameters in the request.
error:
type: string
description: Contains an error identifier. (e.g., "invalid-param")
message:
type: string
description: >-
Explains the nature of the invalid input (for example, "name
invalid").
detail:
type: string
description: >-
Offers further context on the error. (e.g., expected pattern for the
organization name)
required:
- status
- error
- message
- detail
x-apidog-orders:
- status
- error
- message
- detail
x-apidog-ignore-properties: []
x-apidog-folder: ''
Item-exists:
type: object
properties:
status:
type: string
description: >-
Indicates that the request failed because an organization with the
same identifier already exists or is protected.
error:
type: string
description: Contains an error identifier. (e.g., "item exists")
message:
type: string
description: States that the organization cannot be created due to a conflict.
detail:
type: string
description: Provides additional context.
required:
- status
- error
- message
- detail
x-apidog-orders:
- status
- error
- message
- detail
x-apidog-ignore-properties: []
x-apidog-folder: ''
securitySchemes:
Bearer token:
type: bearer
scheme: bearer
description: >-
Enter your Access Token. You can obtain this by calling the /be/v1/login
endpoint. Use the Refresh token to get a new Access token when it
expires.
servers:
- url: https://Example-Server.com
description: Default
security: []
```