6  Users and service accounts

Sophea Portal owns people, invitations, Teams, and workspace access. Nous receives the resulting workspace membership and role so it can authorize chat and administration. Use this page to verify that Portal access has reached Nous and to manage service-account API keys.

For instructions on inviting people, assigning direct workspace access, or granting access through a Team, see Organizations and workspace access.

6.1 Verify synchronized users

Open Settings and select Users, or navigate to /app/admin/users.

The user table shows the people currently known to this Nous workspace, including their email, synchronized role, and account state. Treat it as a verification surface, not the source of truth for access.

Important

In Portal-managed deployments, Nous does not send workspace invitations, approve join requests, cancel invitations, or own Team membership. Perform those operations on the workspace Access page or the Organization People & Teams page in Portal.

If Portal access changed but Nous still shows the old state:

  1. Confirm the person still has an active access source in Portal.
  2. Check direct grants and every Team the person belongs to. Removing one source does not remove access when another source remains.
  3. Ask the person to reopen the workspace from Portal so the current account mapping is synchronized.
  4. If the state still differs, report the workspace name, user email, expected role, and the access source shown in Portal to Sophea support.

Do not repeatedly invite the person or create a second account. Invitations are bound to the invited email address, and duplicate identities make access harder to audit.

6.2 Understand Nous roles

Portal resolves the effective workspace role before synchronizing the account into Nous.

Nous role Typical workspace meaning Capabilities
Admin Workspace owner or workspace admin Manage workspace configuration, connectors, document sets, agents, actions, integrations, and synchronized users.
Basic Workspace member Use chat, projects, available knowledge, and shared agents. Members can also create their own projects and agents where the product is enabled.
Limited Restricted service account Read supported resources and send chat messages without general administration.

Organization roles and effective workspace roles are different. An Organization admin receives workspace-admin authority across that Organization’s active workspaces. A direct workspace admin manages only that workspace and does not gain Organization people or Team management.

6.3 Service accounts

Service accounts represent scripts, scheduled jobs, and integrations that call the Nous API without a browser session. They are workspace-scoped and use bearer tokens.

Open Settings > Service Accounts, or navigate to /app/admin/service-accounts.

6.3.1 Create a service account

  1. Click New Service Account.
  2. Enter a name that identifies the system and purpose, for example Nightly policy check.
  3. Choose Basic or Limited permissions. Admin service accounts are provisioned through Portal rather than this Nous page.
  4. Click Create Account.
  5. Copy or download the token immediately and store it in a secret manager.
Warning

The token value is shown once. If you close the dialog before storing it, regenerate the token. Never put service-account tokens in source control, screenshots, chat messages, or plain configuration files.

Send the token as a bearer credential:

curl -H "Authorization: Bearer $SOPHEA_SERVICE_TOKEN" \
  https://nous.example.com/api/me

6.3.2 Choose the minimum role

  • Admin can call administrative endpoints. Use it only when the integration must change workspace configuration.
  • Basic is the default for automation that needs ordinary user-level APIs.
  • Limited is appropriate for integrations that only need supported read and chat operations.

Create separate service accounts for separate systems. This gives every integration an independent audit identity and lets you rotate or revoke one token without interrupting others.

6.3.3 Rotate or revoke a token

  • Use Regenerate when a token may be exposed or reaches your rotation date. The previous token stops working immediately.
  • Use Delete Account when the integration is retired. Existing audit entries remain attributable to that service account.

After every rotation, confirm the calling system uses the new token before considering the operation complete.