Skip to main content
MeshAgent uses secrets to keep sensitive information (like API keys, database credentials, or OAuth tokens) safe and scoped to the right place. Secrets ensure that credentials never leak across services or users, and that only the right container or participant can access them. There are two complementary systems for secrets:
  • Project secrets: Defined by project admins. These are long-lived key/value bundles and registry credentials used by project services. They’re injected at service startup as environment variables or used to authenticate when pulling private images.
  • Runtime secrets: Collected at room runtime. These are per-user credentials (like OAuth tokens) managed by the Secrets API (room.secrets). They’re tied to participants inside a room and may be refreshed or delegated between participants.
Both systems solve different problems but follow the same principles: least privilege, scoped access, secure storage.

​
Why two systems?

  • Project secrets cover infrastructure needs: database URIs, API keys, registry credentials that your services require consistently across rooms.
  • Runtime secrets cover user-specific needs: a participant’s OAuth token or a delegated credential that allows one agent to act on behalf of another during a live session.
Keeping them separate ensures:
  • Project services remain stable with long-lived or shared credentials.
  • User sessions remain secure with ephemeral, per-participant credentials.

​
Key terms

  • Secret Keys: Named key/value collections attached to project services as environment variables.
  • Image Pull Secrets: Registry credentials used only to pull private images.
  • Secrets API: The interface (room.secrets) that allows agents or tools to request, store, refresh, and revoke participant-scoped credentials (including OAuth flows).
  • Service vs ServiceTemplate: A Service manifest defines how to configure a project wide service for deployment including what secret keys or pull secrets the service requires. A ServiceTemplate manifest describes how room services are configured, including user provided variables.

​
Choosing the right secret type

If you need…Use…
A project-wide API key or database URI available to your backend servicesSecret Keys
To pull images from a private container registryImage Pull Secrets
A user’s OAuth token inside a room sessionSecrets API

​
Next steps