Employees and permissions

An employee account is a separate login identity (own email and password) that works on the owner account's data. The owner grants the employee permissions from a closed registry, e.g. read-only access to documents or full invoicing. Through the API you can automate creating such accounts, e.g. when onboarding a new employee in your HR system.

API scopes: employees:browse, employees:create, employees:update, employees:delete.

One distinction matters: employee permissions are not the same as API scopes. Scopes limit what your API token can do. Employee permissions limit what a person can do after logging into the Fakturnia app. An API token always acts on behalf of the owner account.

Permission registry#

The list of available permissions with labels and descriptions (for your UI). Only requires a valid token, no extra scope:

curl -s https://prod.api.fakturnia.pl/external/v1/employees/permissions \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": {
    "permissions": [
      { "key": "documents:read", "label": "Podgląd dokumentów", "description": "Przeglądanie faktur…" },
      { "key": "documents:write", "label": "Wystawianie dokumentów", "description": "Tworzenie, edycja…" }
    ]
  }
}

Treat the registry like a dictionary: fetch it instead of hardcoding keys. Unknown keys sent on create or update are simply ignored. Labels and descriptions are in Polish, matching the Fakturnia app UI.

Creating an employee account#

curl -s -X POST https://prod.api.fakturnia.pl/external/v1/employees \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jan",
    "lastName": "Kowalski",
    "emailAddress": "jan@firma.pl",
    "password": "a-safe-password",
    "permissions": ["documents:read", "documents:write"]
  }'

Rules:

• the email is globally unique across Fakturnia; a collision returns 409 with the EMAIL_TAKEN code,
• the password needs at least 8 characters (422 otherwise),
• an owner account can have at most 20 employee accounts (409 EMPLOYEE_LIMIT_REACHED),
• the response never contains the password.

Listing, updating and deleting#

# List
curl -s https://prod.api.fakturnia.pl/external/v1/employees \
  -H "Authorization: Bearer $TOKEN"

# Update: change permissions and deactivate
curl -s -X PUT https://prod.api.fakturnia.pl/external/v1/employees/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "permissions": ["documents:read"], "isActive": false }'

# Delete
curl -s -X DELETE https://prod.api.fakturnia.pl/external/v1/employees/{id} \
  -H "Authorization: Bearer $TOKEN"

All update fields are optional: send only what changes. permissions replaces the whole list. Set a new password with the password field.

Deactivation vs deletion. isActive: false blocks the account immediately (the employee's active sessions are ended) but keeps the email on the account. Deletion removes the account permanently and the email becomes available again. Permission changes also apply immediately, without the employee logging in again.

One account and its activity#

GET /employees/{id} returns one account (without the password), 404 for a foreign one. GET /employees/{id}/activity is the employee journal: logins with device and IP address, account changes, document actions and warehouse operations, newest first, with the before / nextBefore cursor and a scope filter. The entry shape is described in History & activity.

Best practices#

• Grant minimal permissions and extend as needed. Start with documents:read; implied permissions are attached automatically (for example documents:write adds documents:read), so you do not have to build complete sets yourself.
• Fetch the permission registry on every sync. GET /employees/permissions is a dictionary: new permissions appear in it without an API version change, and unknown keys in writes are silently ignored. A hard-coded list in your UI will lie.
• Offboard in two steps. First isActive: false (ends sessions immediately, keeps the email and history), then DELETE after a transition period if the account should disappear for good.
• Handle 409 EMAIL_TAKEN explicitly. The email is unique across all of Fakturnia, not just your account, so a collision may involve a completely unrelated account. Show the user a message instead of retrying.
• Rotate passwords with PUT and the password field. There is no separate reset endpoint; a password change does not end active sessions, so combine it with a brief deactivation if you need that.