Authentication & authorization
Alquimia Platform supports multiple authentication mechanisms so you can match the control to the caller: service-to-service requests, end-user sessions, and workload identity for agents themselves.
Authentication methods
Section titled “Authentication methods”| Method | Best for |
|---|---|
| API token | Service accounts and internal clients |
| JWT / OIDC | End users authenticated through Keycloak or another identity provider |
| SPIFFE/SPIRE | Workload identity for agents and runtime pods in Kubernetes |
API tokens
Section titled “API tokens”API tokens are long-lived credentials issued to trusted services. They are validated by the runtime on protected endpoints. Tokens should be stored in Vault or a Kubernetes secret, not committed to source control.
Use API tokens for backend services that call Alquimia Platform without an interactive user context.
JWT and OIDC
Section titled “JWT and OIDC”The runtime can validate JWTs from a Keycloak realm or any OIDC-compatible provider. Claims in the token are mapped to user identity and can be used for agentspace-level authorization.
Use JWT or OIDC when end users interact with agents directly through a web or mobile application.
Workload identity
Section titled “Workload identity”In Kubernetes, runtime services and agents can authenticate using SPIFFE identities issued by SPIRE. This allows Vault to issue short-lived, identity-bound credentials instead of shared tokens.
Workload identity reduces the risk of credential theft and makes it easier to attribute every secret fetch to a specific workload.
Authorization
Section titled “Authorization”Authorization is enforced at three levels:
- Endpoint access — which callers can invoke inference, registry, or state endpoints.
- Agent role tier — each agent is assigned a capability tier:
reader,editor, oroperator. The tier is an identity-plane ceiling, not a permission list. - Tool and knowledge policy — the
ToolAuthzPolicyandKnowledgeAuthzPolicydecide, per operation and per topic, whether a tool runs, requires human approval, or is denied outright.
In production, set DefaultToolAuthzPolicy(default_deny=True) and DefaultKnowledgeAuthzPolicy(default_deny=True) so that unclassified tools and unregistered knowledge topics are denied by default. See Authorization policies for the full policy model, per-operation classification, and topic access control.
Agentspaces
Section titled “Agentspaces”An agentspace is the primary authorization boundary. Users and services can be granted access to one or more agentspaces, and secrets are scoped within them. Design agentspaces to match your organizational or environmental boundaries.
Choosing an auth model
Section titled “Choosing an auth model”| Deployment | Recommended model |
|---|---|
| Local development | API token or static credentials |
| Internal services | API token with network controls |
| User-facing applications | JWT/OIDC through your identity provider |
| Kubernetes production | SPIFFE workload identity + Vault dynamic credentials |