Create a group

POST 
/groups

Creates a group in your tenant, optionally with members.

A new group grants nothing by itself. It becomes an access path only once a permission set is assigned to it with POST /permission-set-assignments, and from that moment everyone in it holds that access.

Three shape notes. The response is 200, not 201, and carries no Location header. A name 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. And subGroups in the request body is accepted and then ignored by everything.

Members named in users are added after the group exists, and the group is read back before that happens, so the response never reflects them. Each add is best-effort: a username that matches no user is skipped silently and the call still returns 200 regardless. Confirm the membership afterwards with GET /groups/{groupName}/members.

The body of this response is the directory's own administrative group 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 group was created. The body is the directory's representation of the group as stored, read back before any members named in users were added.

400

The request body was rejected and no group 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 (including no body at all) returns the ordinary error envelope, with a single error string. A name that used a character outside the allowed set returns the validation envelope instead, which carries an errors array and no error key, so a client that reads only error sees nothing.

Note what is not checked here. A missing or empty name is not a 400: it passes Prism's validation, reaches the directory, and comes back as a 500. So does a duplicate name.

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 group could not be created. This status covers several causes that are arguably client errors and would elsewhere be a 4xx: a name already in use, a missing or empty name, and a value the realm's own rules reject. Read error to tell them apart.

A failure here means no group exists. Failures while adding the users named in users never reach this branch; those return 200.