Skip to main content

Namespace API

A namespace is Trivore ID's multi-tenancy boundary — see Namespace for the concept and the many configuration options available on one. This page covers managing namespaces themselves through the Management API, for example as part of automated customer onboarding.

Listing namespaces​

curl "https://{your-id-server}/api/rest/v1/namespace" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

This lists every namespace the caller can access. It requires one of the ORGANISATION_VIEW, ORGANISATION_VIEW_ALL, or ORGANISATION_VIEW_MANAGED permissions. Unlike most list endpoints, this one doesn't support filter, startIndex, or count — it always returns every accessible namespace at once. Add all=true to list every namespace on the instance instead of only the ones the caller can access, which additionally requires ORGANISATION_VIEW_ALL.

Creating a namespace​

curl -X POST "https://{your-id-server}/api/rest/v1/namespace" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "acme-corp",
    "name": "Acme Corp"
  }'

Requires the ORGANISATION_CREATE permission. code is the short, unique, URL-safe identifier used to reference the namespace elsewhere (it's the value that shows up as nsCode on the resources inside it) — pick it carefully, since it's more disruptive to change later than name.

The two fields above are enough to get started; a namespace has dozens of further optional settings (email domains, username policy, password requirements, and so on) — see Namespace for what's available, or your instance's /apidoc for the full schema.

Reading and updating a namespace​

curl "https://{your-id-server}/api/rest/v1/namespace/{idOrCode}" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

{idOrCode} accepts either the namespace's id or its code. Update it with a PUT request in the same shape as creation — given fields overwrite existing values, so include every field you want to keep, not just the ones you're changing.

Deleting a namespace​

curl -X DELETE "https://{your-id-server}/api/rest/v1/namespace/{idOrCode}" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

This is a destructive, permanent operation on the namespace and everything in it — there's no archive/purge grace period like there is for individual user accounts. Consider whether locking or otherwise winding down a namespace's use is a safer fit than deleting it outright.

Last updated on