Create a user

POST 
/users

Creates a user in your tenant.

Send "enabled": true. The field has no default: omit it and the user is created unable to log in, with nothing in the response saying so beyond enabled: false.

Three things this operation does after the user exists, none of which are reflected in the response body, since it is read back the instant the user is created, before any of them run:

• The directory's default realm role is removed.
• The offline_access realm role is granted.
• The user is added to each group named in groups.

All three are best-effort. In particular a group name that matches no group is skipped silently and the call still returns 200, so a typo in groups looks exactly like success. Confirm memberships afterwards with GET /users/{username}/effective-assignments.

Two shape notes. The response is 200, not 201, and carries no Location header. And a username or email that is already taken comes back as a 500, not a 409. Prism does not translate the directory's conflict, so read error to tell a duplicate from a genuine failure.

The body of this response is the directory's own administrative user representation, passed through unmodified. Prism does not map it to a shape of its own, so its exact field set depends on the version and the configuration of the directory behind your deployment, and additional fields may be present that are not listed here. Treat the response as sensitive: do not log it, and read only the fields you need.

Request

Responses

200

The user was created. The body is the directory's representation of the user as stored, before the role and group steps described above ran.

400

The request body was rejected and no user was created.

This status has two different body shapes, and you have to look at the keys to tell them apart. A body that was not valid JSON returns the ordinary error envelope, with a single error string. A body whose username, email, firstName or lastName used a character outside the allowed set returns the validation envelope instead, which carries an errors array and no error key at all, so a client that reads only error sees nothing.

Note what is not checked here. Prism enforces no required fields of its own; username is marked required above because the request cannot succeed without it, not because Prism rejects a body that omits it. Nor is email checked for being a real address. A missing username and a duplicate username are both 500s, not 400s.

401

Authentication failed: the X-API-Token header was missing, malformed, expired or not recognised.

This response is text/plain, not JSON. It is written by http.Error in the authentication middleware, which runs before any handler and therefore before anything that would build a JSON envelope. A client that unconditionally JSON-parses response bodies will fail on this one, so check the status code first.

403

The token is valid, but it is not allowed to act on this tenant.

An API token is minted inside one tenant and stays bound to it for life. Sending it to a path whose tenant segment names a different tenant is refused here, in middleware, before the operation runs, so this says nothing about the resource you asked for, only about which tenant the path named. Check the tenant server variable against the console the token was created in.

404

No tenant matches the tenant segment of the request path.

500

The user could not be created. This status covers several causes that are arguably client errors and would elsewhere be a 4xx: a username or email already in use, a missing username, and a value the realm's own rules reject. Read error to tell them apart.