When working with users via the API, distinguish between two separate operations: creating a global user, which is created at the service level, and adding a user to a specific company, where the user gets access and a role. Without being added to a company, creating a user has no practical effect on access to that company.

ℹ️ Global users live outside the company database, at the endpoint /u. Users assigned to a company, on the other hand, are records in the /c/{firma}/uzivatel register within that company.

Creating a global user

You create a global user with a PUT or POST request to the endpoint /u.json with the header Content-Type: application/json and the data in the request body. To find out which fields are available, send a GET request to the same endpoint.

PUT https://demo.flexibee.eu/u.json
Content-Type: application/json

{
  "username": "novy_uzivatel",
  "givenName": "Jan",
  "familyName": "Novák",
  "email": "jan.novak@example.com",
  "userType": "READ_ONLY",
  "password": "tajne_heslo_123",
  "blocked": false,
  "permissions": {
    "manageAll": false,
    "createCompany": false,
    "deleteCompany": false,
    "createUser": false,
    "changePassword": false,
    "grantPermission": false,
    "licenseMgmt": false
  },
  "defaultRole": "UZIVATEL",
  "overrideRole": false,
  "apiAccessEnabled": false
}

User type

The value of userType is validated — an invalid value returns 400 with the code invalidUserTypeUsed and the user is not created. The values in use are NORMAL, READ_ONLY, REST_API, and AUTOMATIC.

Server permissions

The permissions object corresponds to the server permissions as you see them in the application. They are particularly suitable for the ADMIN role and take the values true and false:

Permission	What it allows
`manageAll`	Managing all companies on the instance.
`createCompany`	Creating companies.
`deleteCompany`	Deleting companies.
`createUser`	Creating users.
`changePassword`	Changing users' passwords.
`grantPermission`	Granting permissions to users.
`licenseMgmt`	Managing licenses.

Editing a global user

Editing is done with a PUT request to the endpoint /u/{uzivatel}.json; in the body, include only the fields you want to change.

PUT https://demo.flexibee.eu/u/novy_uzivatel.json
Content-Type: application/json

{
  "email": "novy.email@example.com"
}

A request for a nonexistent user returns 404 with the code uzivatelNeexistuje.

Adding a user to a company

After you create a global user, you need to add the user to a specific company. This is done with a PUT request to the company register /c/{firma}/uzivatel, where you specify the user and the role the user should have in that company:

PUT https://demo.flexibee.eu/c/demo/uzivatel
Content-Type: application/json

{ "winstrom": { "uzivatel": [ { "id": "code:novy_uzivatel", "role": "code:ADMIN" } ] } }

In the example above, the user novy_uzivatel is added to the company demo with the role ADMIN. A nonexistent role results in the error notObjectIdentifier and the record is not created.

🚨 The company register does not check that the global user actually exists — if there is a typo in id, the record is created without an error and returns created: 1. This creates a company user with no corresponding global account. After adding a user, always compare the output of /c/{firma}/uzivatel with the output of /u.json.

ℹ️ The default role set when creating a global user (defaultRole) and the role assigned in a company are two different things.

Editing a user's role in a company

A role is changed with the same request used for adding a user — PUT to /c/{firma}/uzivatel with the new value of role:

PUT https://demo.flexibee.eu/c/demo/uzivatel
Content-Type: application/json

{
  "winstrom": {
    "uzivatel": [
      {
        "id": "code:novy_uzivatel",
        "role": "code:SKLADNIK"
      }
    ]
  }
}

Removing a user from a company

If you need to revoke a user's access to a specific company, delete the user's link to the company using the delete action in the uzivatel register:

PUT https://demo.flexibee.eu/c/demo/uzivatel
Content-Type: application/json

{ "winstrom": { "uzivatel": [ { "@action": "delete", "id": "code:novy_uzivatel" } ] } }

⚠️ This step removes the user from the specific company — but if it was the only company assigned to the user, the user is deleted globally. If there are historical records in the database linked to the user, the removal will not go through; in that case, use user blocking.

Blocking a user

Blocking is done with a POST request to /u/{uzivatel}.json with the blocked flag. The optional blocked@message field stores the reason:

POST https://demo.flexibee.eu/u/novy_uzivatel.json
Content-Type: application/json

{
  "blocked": true,
  "blocked@message": "Blocked from API"
}

The blocked value can also be sent as form data (blocked=true).

⚠️ Blocking a user frees up their license and prevents them from logging in. To unblock the user, send the same request with the value false.

Listing all users

An overview of all global users is returned by GET to /u.json:

GET https://demo.flexibee.eu/u.json

For each user, the fields username, userType, blocked, permissions, overrideRole, createDt, licenseGroup, twoPhaseAuthEnabled, resetTokenFilled, and apiAccessEnabled are always filled in. The fields email, givenName, familyName, defaultRole, lastLoginDate, and lastApiDate appear in the response only if they have a value.

📝 In the list, users.user is an array, whereas a request for a single user (/u/{uzivatel}.json) returns users.user as a single object. The code that processes the response must be prepared for this.

Listing users in a specific company

Users linked to a specific company are returned by the company register:

GET https://demo.flexibee.eu/c/demo/uzivatel.json?limit=0&detail=full

⚠️ The limit=0 parameter overrides the default limit of 20 records, so you get all users of the given company. The detail=full parameter lists all fields and their values — see detail levels.

Listing roles in a company

You can find the roles available in a company by querying the role register. For a clear list, request only the ID, code, and name:

GET https://demo.flexibee.eu/c/demo/role.json?limit=0&detail=custom:id,kod,nazev

🚨 Here, detail=full returns a list of all configured permissions, which is over 10,000 rows per role. If you need to read the permissions, limit the query to a single role: GET /c/{firma}/role/code:ADMIN.json?detail=full.

Roles are read-only via the API — attempting to import them returns 400 with the code importNotAllowed.

Endpoint overview

Operation	Method and endpoint	Note
Creating a global user	`PUT` or `POST /u.json`	JSON body
Editing a global user	`PUT /u/{uzivatel}.json`	JSON body, only the fields being changed
Adding a user to a company	`PUT /c/{firma}/uzivatel`	JSON body with `id` and `role`
Editing a user's role in a company	`PUT /c/{firma}/uzivatel`	JSON body
Removing a user from a company	`PUT /c/{firma}/uzivatel`	the `@action: delete` action
Blocking a user	`POST /u/{uzivatel}.json`	the `blocked` flag; can also be sent as form data
Listing all users	`GET /u.json`	global users
Listing users in a company	`GET /c/{firma}/uzivatel.json?limit=0&detail=full`	users of a specific company
Listing roles	`GET /c/{firma}/role.json?limit=0`	choose your own detail level, be careful with `detail=full`

What to watch out for

Creating a user and adding the user to a company are two separate operations — you need to perform both.
The company user register does not verify that the global account exists, so a typo in the username does not result in an error.
Listings with detail=full can be very large and harder to read.
Roles are read-only via the API; you cannot write to them.
Fine-tune your user management via the API in a test environment or against a test database.

Managing Users via the API