Workload identities
Give a Coderunner or script access to chosen Data Vault collections only, instead of the workspace-wide access of an M2M client.
A workload identity is a named credential for code that needs to use some of your Data Vault collections, and nothing else. It belongs to one workspace. You grant it read, write or delete on specific collections, and its tokens work only there.
Use one when an M2M client is too broad. An M2M client acts like a Writer for the whole workspace: every collection and every file. A workload identity sees only the collections you grant it.
Workload identities are managed through the API and the gf CLI. The Client Portal doesn't have a page to create one; it shows an identity's grants in a collection's access settings.
What it can do
- Read, write or delete documents in the collections you grant it, at the level you grant.
- See in the collection list only the collections it has a grant on.
It can't call most other Groundfloor APIs. For example, it can't change feature flags, and it can't read or change a collection's access settings. Those calls fail with 403.
Who can manage them
| To | You need |
|---|---|
| List identities and see their access | Member role or above in the workspace |
| Create, rename or delete an identity, bind it to a Coderunner, or grant it a collection | Admin or Owner in the workspace (or Owner or Admin in its organization) |
| Mint a token | Writer role or above |
Your app's users can't grant an identity access to a collection, even with the admin role; only workspace Admins and Owners can.
Set one up
Create the identity
POST https://platform.groundfloor.cloud/v1/workspaces/{workspace_id}/workload-identities with a name (up to 120 characters) and, optionally, a slug of lowercase letters, digits and hyphens. The response has the identity's id.
Grant it collections
Replace a collection's grants with PUT https://platform.groundfloor.cloud/v1/workspaces/{workspace_id}/vault/collections/{name}/acl, and include a grant for the identity:
{
"grants": [
{ "principal_type": "workload_identity", "principal_id": "<identity-id>", "action": "read" }
]
}PUT replaces the whole list, so send the grants that should remain as well. The identity must be in the same workspace.
Bind a Coderunner (optional)
PUT …/coderunners/{coderunner_id}/workload-identity with { "workload_identity_id": "<identity-id>" } binds a Coderunner to the identity, and null unbinds it. A bound Coderunner can then ask for a token for its identity with POST …/coderunners/{coderunner_id}/vault-token. A Coderunner with no identity can't mint a token.
Get a token
gf identities ls
gf identities mint --identity <identity-id>gf identities mint prints a short-lived token (the Bearer token) to standard output. The first mint for an identity also returns a refresh secret, once; save it straight away. Add --rotate-refresh to replace the refresh secret with a new one.
The token lasts a few minutes (300 seconds by default; the response shows expires_in). To get a new one without a person signed in, code sends the refresh secret to POST https://platform.groundfloor.cloud/v1/workspaces/{workspace_id}/workload-identities/{identity_id}/vault-token/refresh with { "refresh_secret": "…" }. The refresh secret must be at least 16 characters. Treat it like a password: keep it in Secrets, never in code.
Use the token as a Bearer token on the Data Vault API requests the identity is allowed to make.
A deploy gives a Coderunner its M2M client's credentials, not a workload identity token. Your code gets its identity token by sending its refresh secret, as above.
Rotate or remove access
- Take away a collection:
PUTthat collection's grants without the identity. - Rotate the refresh secret:
gf identities mint --identity <id> --rotate-refresh. The old refresh secret stops working. - Delete the identity: this removes its Data Vault grants and unbinds its Coderunners.
Creating, changing and deleting identities, binding, and minting tokens are all recorded in the activity log.
Troubleshooting
| Problem | Likely cause | What to do |
|---|---|---|
403 on minting for a Coderunner | The Coderunner isn't bound to an identity | Bind one |
409 on minting for a Coderunner | It is a legacy Coderunner with no identity | Bind an identity, then mint again |
403 "Workload identity cannot call this API" | You used the identity token on an API it can't use | Use it for Data Vault requests only; use an M2M client or a person's token elsewhere |
400 "workload identity is not in this workspace" | The id belongs to another workspace | Use an identity from this workspace |
| Collection missing from the list | The identity has no grant on it | Grant it as above |
Next steps
- M2M tokens — workspace-wide machine access.
- Data Vault — the collections an identity can use.