Organization & Permissions

NICo does not maintain its own user directory. Identity, org membership, and role assignments are all managed in the upstream identity provider. The REST API reads role claims from the authentication token on every request. Adding or removing a user is done in the identity provider, not through nicocli.

NICo accepts tokens from any OIDC-compatible IdP. The bundled dev Keycloak (deployed by setup.sh and documented in the Quick Start Guide) is the recommended starting point and the reference implementation for IdP wiring — you can use it as-is for evaluation, or model your production IdP setup after it. Configure additional or replacement IdPs via the issuers block in carbide-rest-api’s config; see the Reference Installation guide for the configuration surface and the claim mappings NICo expects (org name, display name, role claim).

Roles

NICo’s authorization model has three roles, all managed in the upstream identity provider:

A single user can hold roles in multiple orgs simultaneously. On dev/service-account orgs, one user typically holds both Provider Admin and Tenant Admin in the same org.

Adding a User to a Tenant

1. Add the user to the IdP organization (or group) that maps to the tenant.
2. Assign the TENANT_ADMIN role at the org level.
3. Have the user authenticate with nicocli and verify: nicocli user get

The exact steps depend on your IdP. For the bundled dev Keycloak, this is realm administration in the Keycloak admin console — create the user, add them to the realm group that maps to the tenant org, and assign the role. See the Quick Start Guide for the realm layout.

Adding a Provider Admin

1. Add the user to the infrastructure provider’s IdP organization.
2. Assign the PROVIDER_ADMIN role.
3. Verify: nicocli user get

Same caveat as above — this is an IdP admin task, not a nicocli operation.

Verifying Your Identity

nicocli user get

Example response for a human user:

1
{
2
  "id": "<user-uuid>",
3
  "email": "alex@acme-corp.com",
4
  "firstName": "Alex",
5
  "lastName": "Chen",
6
  "created": "2026-04-23T00:54:27.452525Z",
7
  "updated": "2026-05-15T17:25:23.884166Z"
8
}

Service accounts have empty email/firstName/lastName. Human users have those populated from the IdP.

This endpoint does not return role information directly — roles are in the token and validated server-side. Confirm which roles you hold by attempting role-gated operations: nicocli allocation list requires Provider Admin; nicocli tenant get-current-tenant requires Tenant Admin.

If your deployment is configured for service-account auth, use nicocli service-account get to retrieve the current org’s service-account status, including the auto-created provider and tenant IDs.

Listing Tenant Members

NICo does not expose a “list users in this tenant” endpoint. Use the IdP’s admin console or API to view members and roles.

For audit purposes, NICo’s audit log records which user performed each operation:

nicocli tui
> audit list

Removing a User

Remove the role assignment (or org membership) in the identity provider. The change takes effect on the user’s next authentication attempt.

Day One User Setup Checklist

1. Create the IdP organization (or group) for the tenant.
2. Invite at least one user with TENANT_ADMIN so they can provision the tenant.
3. Invite additional team members with appropriate roles.
4. Verify from the tenant side: nicocli user get and nicocli tenant get-current-tenant.
5. On the provider side, ensure at least one user holds PROVIDER_ADMIN.