Skip to content
xmemoryxmemory Website

Roles and access

A role is a named set of permissions, such as data.read and data.write. An assignment gives that role to a user or API key for a set of resources. The same organisation role can serve both. For a request to succeed, an assignment must grant the operation on the requested target.

Give a teammate read access and one place to write

Section titled “Give a teammate read access and one place to write”

Suppose your organisation has two instances, Support and Sandbox. A teammate needs to read both and write only to Sandbox. To invite them, the user or API key sending the invitation needs user.invite and authority to grant each selected role at its chosen scope. This applies in the Console and when an agent runs the CLI.

Tell an agent with access to xmemcli who needs access (a teammate’s email or an API key’s name or ID), what they should be able to do, and where (the organisation, a cluster, or specific instances). You can describe the work in your own words and ask the agent to find the matching permissions.

Use xmemcli to invite sam@example.com. Sam needs to sign in to the Console, see and read every instance in our organisation, and write only to Sandbox. Which roles and scopes would give Sam that access?

When you ask the agent to send the invitation, it can use xmemcli org manage with your authorised CLI session or key. Sam receives the assignments on accepting the invitation. You can also run the CLI commands yourself.

  1. In the Console, open Roles. Choose or create a reader role with data.read and a writer role with data.write. Include instance.get in the reader role if the teammate needs instance metadata or schema. For Console sign-in, ensure the teammate also receives portal.login.
  2. Under Users, choose Invite user and select Email. Enter the teammate’s address. Add the reader role and choose Whole organisation.
  3. Choose Add assignment, select the writer role, and select the Sandbox instance. Send the invitation. The recipient signs in and accepts using the verified email address. Under Users, review the resulting assignments. For an existing user, edit their assignments directly.
  4. To give an application the same access, open API Keys, create a key from your user session, and add the same two assignments. Store the issued secret when you create the key. Inspecting a key later shows its identity and grants.

Assuming these are the only data grants, each credential has the following access. Whole organisation also covers future instances.

OperationSupportSandbox
Read memoryAllowed by readerAllowed by reader
Write synchronouslyDeniedAllowed by writer
Queue an asynchronous writeDeniedDenied until a role grants data.write_async here

For an email-free invitation, select Link and share the link with the intended recipient. The recipient still needs a verified user session. Resending rotates the token and invalidates the earlier link. Pending invitations can be revoked.

ScopeWhat it covers
Whole organisationApplicable resources throughout the organisation.
Created by meResources created by the user, or by the owner for an API-key assignment. The API represents this with organisation scope and access_mode: mine.
Selected clustersThe selected clusters and applicable operations on their current member instances. Adding or removing an instance can change access immediately.
Selected instancesThe named instances. Seeing an instance and its cluster IDs does not grant access to its siblings.

Adding an instance to a cluster can give that cluster’s users and API keys access to it. See Change cluster membership for the permissions and steps.

A key uses its own assignments independently of its owner’s grants and status. Deactivate the key to withdraw all access. To withdraw one grant, you can remove its Sandbox writer assignment and keep its organisation-wide reads. Inspect the role and target on each assignment when diagnosing a denied operation.

A user session can create a key with multiple assignments. A key issuing a child key needs api_key.create and can delegate one role/scope binding within its own authority. The child is bounded by its parent chain and expiry. Narrowing a parent can revoke descendant grants. Restoring the parent does not restore those revoked grants.

Key listings default to the caller’s own keys. Viewing other owners’ keys requires api_key.get and api_key.see_org_keys. Managing another owner’s keys requires api_key.manage_org_keys alongside the operation permission. Only a user session can select a different owner when issuing a key.

See the CLI management workflow, Accounts API, and Python management client.