Service accounts
A service account is a workspace-scoped non-human identity that a workload, such as a workflow worker, uses to authenticate to the Mistral platform. It is a principal in its own right: it has a name, roles, and its own credentials, and it is not tied to any person.
Running a workload under a service account rather than a team member's API key has two advantages:
- the workload keeps working when that person's key is rotated, or when they leave;
- audit logs and hardened deployments name the workload, not a person.
Use a service account for machine-to-machine authentication, such as a workflow worker running in your cluster. Use a personal API key for interactive use, scripts, and development.
How a workload authenticates
A service account on its own cannot authenticate. It needs at least one credential, and there are two kinds.
| Credential | How it works | When to use it |
|---|---|---|
| Workload identity federation | The workload presents a short-lived token signed by a trusted issuer. The platform verifies it using the issuer's public key. No stored secret. | A workload running in a Kubernetes cluster or behind another OIDC issuer. |
| API key | A long-lived key owned by the service account. | A worker running outside of Kubernetes. |
Both are managed from the same place: open the service account and click Add new authentication. Workload identity federation has its own setup, covered in Workload identity federation. Adding an API key is covered in Add an API key.
Create a service account
A workspace admin creates the service account.
- Open Admin Console›Workspace›Service accounts ↗.
- Click Create service account.
- Enter a Name (unique within the workspace) and an optional Description.
- Click Create.
| Field | Required | Notes |
|---|---|---|
| Name | Yes | Human-readable, unique within the workspace. Up to 255 characters. |
| Description | No | Free text to record what the service account is for. |
Roles
A new service account holds the workflow_executor workspace role, which lets its worker register and run workflows. Grant the Developer role in addition when the workload needs to call the platform beyond workflow execution.
Manage this from the Roles section of the service account. See Roles and permissions.
Add an API key
An API key owned by a service account authenticates as that service account, and inherits its roles.
- Open the service account and click Add new authentication.
- In the Add credential dialog, choose API key.
- Optionally enter a Name to help you identify the key later.
- Optionally set an Expiration. Leave it empty for a key that never expires.
- Click Create API key.
The key is displayed once, on creation. Copy it and store it in your secret manager. You cannot retrieve it afterwards.
| Field | Required | Notes |
|---|---|---|
| Name | No | A label to identify the key later. |
| Expiration | No | The last day the key is valid. Your organization can enforce a maximum lifetime. |
The key is scoped to the service account's workspace and to shared connectors only. You cannot move it to another workspace.
An API key is a standing secret: anyone holding it can act as the service account until the key is deleted or expires. Prefer workload identity federation when your workload can present an issuer-signed token.
Manage credentials
The two credential types are listed in different places.
- Workload identity credentials appear in the Credentials list on the service account, with their subject, trusted issuer, and expiry. See Manage and rotate.
- API keys appear in the API keys section for the workspace, alongside keys owned by people. The Principal column shows the owning service account and a Service account badge.
Deleting a service account removes the identity and its credentials, and any workload using them stops authenticating.
Service accounts and hardened deployments
A hardened deployment restricts which principals can register workflows. You can associate a service account with one, and rotating that service account's workload identity credentials then needs no change to the deployment.
An API key is associated separately, as an API key. If your worker authenticates with a service account's API key, add that key to the hardened deployment as well.