---
title: "Administration APIs"
description: "Signer administration APIs to create and manage users and organizations, and how to create the administration API key in the Sys Admin organization."
canonical: "https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/administration"
locale: "en"
product: "Signer"
last_updated: "2026-10-22"
---

# Administration APIs

## Introduction
The administration APIs let you create, manage and change Signer users and organizations.

To call these APIs you need an **administration API key**.

## Creating an administration API key

To create one, create an application and select the `Sys Admin` organization:

![Applications](https://docs.lacunasoftware.com/images/signer/applications.png)

![Create application Sys Adm](https://docs.lacunasoftware.com/images/signer/create-application-adm.png)

Then create the key with the "Keys" button:

![Application keys](https://docs.lacunasoftware.com/images/signer/application-keys.png)

![Application create Administration key](https://docs.lacunasoftware.com/images/signer/application-keys-add.png)

![Create key submit](https://docs.lacunasoftware.com/images/signer/create-key.png)

## Administration operations

Choose one of the use cases below:

* [List users](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/administration#list-users)

* [Update user data](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/administration#update-user-data)

* [List organizations](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/administration#list-organizations)

* [Create an organization](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/administration#create-an-organization)

* [List the users of an organization](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/administration#list-the-users-of-an-organization)

* [Create or update users of an organization](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/administration#create-or-update-users-of-an-organization)

* [Remove a user from an organization](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/administration#remove-a-user-from-an-organization)

* [Organization settings](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/administration#organization-settings)

These and other operations are shown in the following [Postman](https://www.postman.com/) collection: [Signer ADM APIs](https://cdn.lacunasoftware.com/signer/docs/Signer%20ADM-5.postman_collection.json).

### List users

To list the users registered in the system, with their data and permissions, call `GET /api/users`:

```json
GET /api/users?q=
{
    "items": [
        {
            "identifier": "99999999999",
            "phone": null,
            "id": "446e14b9-a661-446a-bb52-66b6c9f1ade9",
            "subject": "17bb43bd-1dac-46ce-95d2-62007bee2aea",
            "name": "User One",
            "emailAddress": "User.One@mailinator.com",
            "parentId": null,
            "rootRoles": [],
            "parentRootRoles": null,
            "subscriptions": [
                {
                    "agentId": "446e14b9-a661-446a-bb52-66b6c9f1ade9",
                    "subscriptionId": "28dd8bc0-ef7a-44e4-b2f8-08da757b7cf1",
                    "roles": [
                        "Admin",
                        "Manager",
                        "Basic"
                    ],
                    "parentRoles": null
                }
            ]
        },
        {
            "identifier": "11096802449",
            "phone": "+55 61 99999-9999",
            "id": "7b06a7ed-43fc-45df-96f8-cb29f4778e22",
            "subject": "ee72e66e-c150-47c3-a8fd-d4d0c6e12ef5",
            "name": "User Two",
            "emailAddress": "user.two@mailinator.com",
            "parentId": null,
            "rootRoles": [],
            "parentRootRoles": null,
            "subscriptions": [
                {
                    "agentId": "7b06a7ed-43fc-45df-96f8-cb29f4778e22",
                    "subscriptionId": "7289e60f-0c1f-4a3d-4b81-08da718c9ef3",
                    "roles": [
                        "Admin",
                        "Manager",
                        "Basic"
                    ],
                    "parentRoles": null
                }
            ]
        }
    ],
    "totalCount": 2,
    "nextCursor": null
}

```

* q (query - `string`): filters the returned users by name, CPF or email (optional).

### Update user data

To update a user's data, call `PUT /api/users/{subject}`:

```json
PUT /api/users/{subject}
{
  "name": "User Name",
  "identifier": "11096802449",
  "emailAddress": "user@mailinator.com",
  "phone": "+55 (61) 99999-9999"
}
```

* `{subject}` is the field of the same name returned with the user's data, as described in [List users](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/administration#list-users).

### List organizations

To list the organizations registered in the system, call `GET /api/admin/organizations`:

```json
GET /api/admin/organizations?limit=1&offset=1&personal=true&q=user

{
    "items": [
        {
            "id": "5aaa9032-1ad0-4c63-3c73-08d9d088eeac",
            "name": null,
            "identifier": null,
            "owner": {
                "id": "6f9d67cc-5cea-4672-b09e-ac04ed2e348f",
                "name": "Novo User"
            }
        }
    ],
    "totalCount": 17,
    "nextCursor": null
}
```

* limit (`int`): number of items per page (optional).

* offset (`int`): page number (optional).

* q (query - `string`): filters by organization name (optional).

### Create an organization

To create an organization, call `POST /api/admin/organizations`:

```json
POST /api/admin/organizations

{
  "name": "newOrg",
  "identifier": "85932577000194"
}
```

### List the users of an organization

To list the users of an organization, call `GET /api/organizations/{id}/users`:

```json
GET /api/organizations/{id}/users?limit=1&offset=0&q=
{
    "items": [
        {
            "id": "7b06a7ed-43fc-45df-96f8-cb29f4778e22",
            "name": "User Name",
            "email": "user.name@mailinator.com",
            "identifier": "11096802449",
            "role": "",
            "parentId": null,
            "accessProfile": {
                "administrator": true,
                "manager": true,
                "parentRoles": null
            },
            "showNameWarning": false
        }
    ],
    "totalCount": 3,
    "nextCursor": null
}
```
* `{id}`: the organization ID.

* limit (`int`): number of items per page (optional).

* offset (`int`): page number (optional).

* q (query - `string`): filters by user name (optional).

### Create or update users of an organization

To create or update users, call `POST /api/organizations/{id}/users`:

```json
POST /api/organizations/{id}/users
{
  "accessProfile": {
    "administrator": true,
    "manager": true
  },
  "name": "User Name",
  "identifier": "11096802449",
  "email": "user@mailinator.com"
}
```

* `{id}`: the organization ID.

### Remove a user from an organization

To remove a user from an organization, call `DELETE /api/admin/organizations/{id}/users/{userID}`:

* `{id}`: the organization ID.
* `{userID}`: the ID of the user to remove.

### Organization settings

These APIs read and change the settings that the organization administrator sees on the organization screen. They are not in the API reference (Swagger). To change settings, the key needs the permission to manage the organization's settings. The administration API key has this permission.

Three settings control document creation:

| Section | Fields | What it does |
| --- | --- | --- |
| `requireFolder` | `enabled` | If `true`, every new document needs a folder. Without a folder, creation fails with the `FolderRequired` error. `null` uses the instance default. |
| `tags` | `tagLabels`, `requireTagOnDocumentCreation`, `requireRegisteredTagLabels` | `tagLabels` is the list of registered tags. If `requireTagOnDocumentCreation` is `true`, every new document needs a tag with a label and a value (`TagRequired` error). If `requireRegisteredTagLabels` is `true`, the tag label must be on the list (`TagLabelNotRegistered` error). |
| `signerPositioning` | `enabled`, `automaticPositioning` | The organization default for [signer positioning of the signature](https://docs.lacunasoftware.com/en-us/articles/signer/integration/documents#signer-positioning). `null` uses the instance default. Available from version 3.0.0. |

An integration can bypass these three requirements on a document with the [`overrides`](https://docs.lacunasoftware.com/en-us/articles/signer/integration/document-fields#document-options) field.

To read a section, use `GET /api/organizations/{id}/settings/require-folder`, `GET /api/organizations/{id}/settings/tags` or `GET /api/organizations/{id}/settings/signer-positioning`. To reset a section to the default, send a `DELETE` to the same route.

To change settings, use `PUT /api/organizations/{id}/settings`:

```json
PUT /api/organizations/{id}/settings
{
  ...
  "tags": {
    "tagLabels": [ "Contract", "Department" ],
    "requireTagOnDocumentCreation": true,
    "requireRegisteredTagLabels": true
  },
  "requireFolder": { "enabled": true },
  "signerPositioning": { "enabled": false, "automaticPositioning": "SignatureSheet" }
}
```

> **Warning**
>
> The `PUT` replaces every section of the organization settings, such as e-mail, reminders and printer-friendly version, not only the sections above. First read the settings with `GET /api/organizations/{id}/settings`, then send back every section with your change. A section you do not send can go back to the default or cause an error.