M2M tokens
Credentials for Coderunners, servers and CI to call Groundfloor without a person signed in.
An M2M (machine-to-machine) token lets code call Groundfloor when no person is signed in: your Coderunners, a CI pipeline, a server of your own. You create an M2M client with a secret, and the code exchanges that secret for a short-lived token.
What an M2M token can do
An M2M client acts like a Writer in its workspace:
- Read and write every Data Vault collection and every file. Collection grants on Site access don't apply to it.
- Deploy and run Coderunners.
- Read feature flags, but not change them.
- Read secrets only if you turn on Read secrets. It can never write or delete secrets.
It can't manage members, app sign-in or access grants.
Create a client
Open M2M tokens
In the Client Portal, go to Administer → M2M tokens and pick the workspace.
Create it
Give the client a name. Tick Can read secrets only if its code needs secrets. Copy the secret now: you can't see it again. Rotate replaces it later.
Use it
- In a Coderunner: attach the client to the Coderunner, then deploy. Your code gets
GROUNDFLOOR_M2M_CLIENT_IDandGROUNDFLOOR_M2M_CLIENT_SECRET. A Coderunner can't use your data or files until a client is attached. - In CI or on your own server: set those two variables, then run
gf m2m token, or call the API as below.
Use one client per Coderunner, and a separate one for CI, so you can rotate and audit each one on its own.
Get a token
gf m2m token # prints a token; not the same as gf token
curl -H "Authorization: Bearer $(gf m2m token)" \
"https://platform.groundfloor.cloud/v1/workspaces/$GROUNDFLOOR_WORKSPACE_ID/vault/collections"From code, exchange the credentials with POST https://platform.groundfloor.cloud/v1/workspaces/{workspace_id}/m2m/token, sending client_id and client_secret. The response has access_token and expires_in, in seconds. Configuration and secrets has a ready-made helper.
Reuse each token until shortly before it expires. Getting a token is limited to 20 a minute per client, and 20 a minute per IP address. Code that gets a new token for every request fails with 429 under real traffic. Treat a 429 or 401 from the token request as something to retry.
Read secrets
Turn on Read secrets for the client, in its row on the M2M tokens page or when you create it. The client can then read every secret in the workspace, in every environment. The change applies to the next token it gets. This is the recommended way to give a Coderunner its secrets; see Configuration and secrets.
Call a Function
A server or another Coderunner calls a Function with an M2M token. gf token is only for trying things out yourself.
Next steps
- Configuration and secrets
- M2M API — clients, scopes and rotation from code.