Get a group

GET 
/groups/:groupName

Returns one group.

This is not an expanded form of what GET /groups lists. That endpoint answers with Prism's own two-field summary; this one answers with the directory's representation of the group. Code that consumes both needs to handle two shapes.

It does not list members or access. Use GET /groups/{groupName}/members for who is in the group and GET /groups/{groupName}/assignments for what the group grants.

The lookup is a search followed by an exact match, not a direct fetch: Prism asks the directory for groups matching the name and then picks the one whose name is exactly equal. The directory returns a bounded number of search results, so in a realm with many similarly named groups a group that exists can fall outside that window and be reported as a 404. A 404 here means "not among the matches the directory returned", which is not quite the same as "does not exist".

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.

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 group in your tenant has this name. Nothing distinguishes a group that never existed from one that has been deleted, from one whose name differs only in case, or from one the search window did not reach.

500

The group could not be read from the directory.