EzSign REST API Users File

Note: The REST API is only available in version 4.6.0 onwards

The users that may call the REST API are held in a users file. It lists each user, the credentials they authenticate with (API tokens or client certificates) and the roles that give them their permissions. The file is set by server.restapi.usersFile in the server properties (see EzSign Properties)

The file is normally created and changed with the EzSign Management Tool (the browser UI, the menu or the CLI), which validates it with exactly the rules the server uses and signs it with the admin key. This page describes the format, for reviewing the file or creating it by other means

Example

{
  "version": 3,
  "roles": {
    "finance-signer": [
      "sign:channel/FINANCE",
      "verify:channel/FINANCE"
    ],
    "batch-crypto": [
      "verify:channel/*",
      "random:channel/BATCH",
      "encrypt:channel/BATCH",
      "decrypt:channel/BATCH"
    ],
    "monitor": [
      "status"
    ]
  },
  "users": [
    {
      "id": "finance-app",
      "description": "Finance application",
      "enabled": true,
      "roles": ["finance-signer"],
      "credentials": [
        { "type": "certificate", "sha256": "3f:5a:...:9c", "label": "production" },
        { "type": "certificate", "issuer": "CN=Example Issuing CA,O=Example Ltd", "serialNumber": "3A:4B:5C:6D" }
      ]
    },
    {
      "id": "batch-service",
      "enabled": true,
      "roles": ["batch-crypto"],
      "credentials": [
        { "type": "apiToken", "sha256": "<SHA-256 of the token>", "label": "batch jobs", "created": "2026-10-28" }
      ]
    },
    {
      "id": "monitoring",
      "enabled": true,
      "roles": ["monitor"],
      "credentials": [
        { "type": "apiToken", "sha256": "<SHA-256 of the token>" }
      ]
    },
    {
      "id": "partner-gateway",
      "enabled": false,
      "roles": ["batch-crypto"],
      "credentials": [
        { "type": "certificate", "subject": "CN=partner-gateway,O=Example Ltd", "issuer": "CN=Example Issuing CA,O=Example Ltd" }
      ]
    }
  ]
}

The File

The file is a JSON object, encoded as UTF-8. It must not be larger than 10 MB

Fields not listed on this page are ignored, and are not kept when the management tool writes the file

Roles

Each entry in roles is a role name and the array of permissions it grants e.g.

"roles": {
  "finance-signer": ["sign:channel/FINANCE", "verify:channel/FINANCE"]
}

A user’s permissions are those of all their roles. Permissions cannot be assigned to a user directly: create a role for each set of permissions and assign it to the users that need it

Permissions

A permission takes the form operation:channel/NAME

The channel name may contain * as a wildcard, matching any characters. Names are compared exactly, including case. For example:

There are also two permissions written on their own, without a channel:

A file with a permission that is not in one of these forms is refused

Users

Each entry in users is an object:

A user with a permissions field is refused rather than ignored, so a user does not silently lose (or keep) access. Move the permissions to a role and assign the role to the user

Credentials

Each credential is an object with a type of apiToken or certificate. A credential can belong to only one user: a file with the same token or certificate on two users, or twice on the same user, is refused

Both types may also have:

API Tokens

{ "type": "apiToken", "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "label": "batch jobs" }

The token itself is never stored, only its hash. The client sends the token in the Authorization header:

Authorization: Bearer ezs_Q2xhdWRlIGdlbmVyYXRlZCB0aGlzIGV4YW1wbGU...

Tokens generated by the management tool are ezs_ followed by 32 random bytes, base64url encoded. The tool shows the token once, when it is created. If it is lost, add a new token and remove the old one

An API token credential must not have any of the certificate fields

Client Certificates

{ "type": "certificate", "sha256": "3F:5A:...:9C" }

The client authenticates with its certificate over TLS. The server first validates the certificate against server.restapi.tls.trustStore (see EzSign Properties), then finds the user it belongs to. A certificate credential identifies the certificate with exactly one of:

Hex values (sha256, sha1 and serialNumber) may be in upper or lower case, and may contain colons and spaces e.g. 3f5a..., 3F:5A:... and 3F 5A ... are all accepted. The invisible characters Windows adds when a thumbprint is copied from the certificate dialog are ignored. Leading zeros in a serial number are ignored

Distinguished names are given as in RFC 2253 e.g. CN=finance-app,O=Example Ltd. They are compared as distinguished names, so differences in spacing and case that do not change the name are ignored

The certificate is matched in this order: sha256, sha1, issuer and serialNumber, subject with issuer, then subject alone. The first match decides the user

Signing

If server.restapi.usersFile.signerCerts is set, the users file must be signed with the private key of one of these admin certificates, so that someone who can change the file cannot give themselves access. See Signing the Users File for creating the admin key and signing with the management tool

The signature is held in a second file, next to the users file, with .sig added to its name e.g. users.json.sig:

{
  "format": "ezsign-users-signature",
  "formatVersion": 1,
  "algorithm": "SHA256withRSA",
  "signedAt": "2026-10-28T13:00:00Z",
  "signer": "CN=EzSign Users Admin,O=Example",
  "signerCertificate": "<base64 DER of the admin certificate>",
  "contentSha256": "<hex SHA-256 of users.json>",
  "signature": "<base64 signature over the exact bytes of users.json>"
}

When the users file must be signed, the server only loads it if:

• The signature file exists and is in the format above
• signerCertificate is one of the certificates in server.restapi.usersFile.signerCerts. The certificate is pinned, not validated against a CA, so list more than one certificate to change the admin key without a break
• The signature verifies over the exact bytes of the users file. Any change to the file, even to spacing, needs a new signature
• The file’s version is not lower than the version already loaded, so an older signed file cannot be put back while the server is running

If signerCerts is not set, the signature is not checked and the server logs a warning each time it loads the file

Loading the File

The server loads the users file when it starts, and again when it is reloaded with the server control tool (see EzSign Control) or from the management tool. If the new file cannot be read, is not valid, is not correctly signed or has a lower version, it is refused, the reason is logged and the server keeps the users it has

The server logs the number of enabled users and the version loaded e.g.

REST: Loaded 3 enabled user(s) from ../config/users.json (version 3)

A file is refused as a whole if any part of it is not valid, for example:

• It is not valid JSON, or has no users array
• A user has an empty or repeated id, no credentials, a permissions field or a role that is not in roles
• A permission is not in one of the forms above
• A credential has an unknown type, a hex value of the wrong length, an invalid distinguished name or serial number, or not exactly one way of identifying a certificate
• The same credential is assigned more than once