soma api-key add <name>
soma api-key rm <name>
soma api-key list
API keys are stored, hashed in the database and are never stored in plaintext. They are also stored hash and encrypted in the soma.yaml file in order to allow you to safely commit your soma.yaml file to version control.
Creating an API key will result in creating a machine (service account) user in Soma DB and you will be prompted for a role to assign this user.
You can review the available roles and permissions here to determine the appropriate role for your use case.
API keys vs Access tokens
It’s best to view access tokens & API keys as proof of identity and interchangeable. They both prove different forms of identity humans (users) or machines (service accounts). Importantly, the roles associated with the access token or API key is ultimately what determines permissions and access to resources. It’s therefore possible to configure API key’s or access tokens to invoke agents or any other API endpoints in Soma.Requests on behalf of a user
When machines (service accounts) make requests on behalf of a user it’s best practice to supply both the API token header (X-Api-Key) as well as the access token Authorization header (Authorization: Bearer <access_token>).
For example:
- if you are proxying requests through your own backend or,
- if agents process user requests that result in invoking other agents or Soma API endpoitns
- Only service accounts can access this resource
- Only users can access this resource
- Only service accounts on behalf of a user with the appropriate role can access this resource