Skip to main content
Access control is a core feature of Soma. It allows you to configure fine-grained access control to agents, functions & API endpoints. Please review the appendix: roles & permissions for a catalog of all available roles & related permissions in Soma. In summary, there are the following roles:
  • admin
  • maintainer
  • read-only maintainer
  • user
  • agent
When creating an API key, you will explicitly associate a role with the API key. This role will determine the permissions of the API key. When creating a user, you will define a mapping from a user group to a role or a scope in their access token to a role. In the case of a user group, when a user is added or removed from a specific group, their role will be updated accordingly. A user can only have one role at a time, the highest role in the hierarchy will be used.

​
Agent invocation endpoints

In addition to the above roles which govern access to Soma API endpoints, you can also provide an additional configuration for agent invocation endpoints. By default, agent’s can not be invoked by any role. When configuring your agent in the relevant SDK using createSomaAgent or create_soma_agent, you can specify an array of all roles that are allowed to invoke the agent. This enables:
  • Agent-only access, where users’ can’t invoke a workflow. Only agent role users can (other agents).
  • User-only access, where agents can’t invoke a workflow. Only user role users can (other users).
  • Maintainer-only access, where users can’t invoke a workflow. Only maintainer role users can (other maintainers).