Skip to content

Machine client

A machine client is a backend, a job or an agent that acts as itself, with no user: a nightly export, a service calling another. It gets access tokens with its own secret (the OAuth client credentials grant) and calls your APIs with them.

You need an API for the token to be for: create it in APIs and roles (here orders-api, with a permission orders:read), and a role that holds that permission.

In Clients, create a client of type Machine. It has no redirect URIs and no origins: nobody logs in through it. Its secret is shown once; keep it in your deployment’s secrets.

With the management API:

POST /v1/environments/{environment id}/clients
Authorization: Bearer sk_dev_...
Content-Type: application/json
{ "name": "Fulfilment job", "type": "machine", "default_api_id": "{orders-api id}" }
{
"id": "6b0c1f8e-…",
"client_id": "your-app-dev-machine-5f7d0f",
"type": "machine",
"auth_method": "client_secret_basic",
"client_secret": "…",
"…": "…"
}

A machine client’s token carries the roles you give the client, and their permissions for the API the token is for. Giving them takes the admin role: open the client in Clients, or:

PUT /v1/environments/{environment id}/clients/{client's id}/roles
Content-Type: application/json
{ "role_ids": ["{reader role id}"] }

The path takes the client’s id, not its client_id. A role that requires two-step login never counts for a machine client.

Terminal window
curl -s https://your-app.auth.dev.seek.services/token \
-u 'your-app-machine-5f7d0f:<client secret>' \
-d grant_type=client_credentials \
--data-urlencode 'resource=orders-api'
{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIs…",
"token_type": "Bearer",
"expires_in": 300,
"scope": ""
}

There is no refresh token and no ID token: ask again when the token runs out. The token’s claims:

{
"iss": "https://your-app.auth.dev.seek.services",
"sub": "your-app-machine-5f7d0f",
"aud": "orders-api",
"client_id": "your-app-machine-5f7d0f",
"sid": "",
"acr": "client",
"amr": [],
"roles": ["reader"],
"permissions": ["orders:read"],
"scope": "",
"…": "…"
}

resource names the API. Without it the token is for the client’s default API; with neither, the request is refused with invalid_target, as it is for an API the client may not name (one of another app, unless it was granted). How long the token lasts is the environment’s machine-token lifetime, five minutes out of the box.

MachineClient fetches a token, keeps it, and fetches a new one a minute before it expires; callers that ask at the same time share one request.

use auth_client::MachineClient;
let issuer = std::env::var("AUTH_ISSUER")?; // https://your-app.auth.dev.seek.services
let client_id = std::env::var("AUTH_CLIENT_ID")?;
// The secret comes from your deployment's secrets, never from the source.
let secret = std::env::var("AUTH_CLIENT_SECRET")?;
let me = MachineClient::new(&issuer, &client_id, &secret, "orders-api");
let token = me.token().await?; // fetched once, reused until a minute before it expires
let http = reqwest::Client::new();
let orders = http
.get("https://api.your-app.com/orders")
.bearer_auth(&token)
.send()
.await?;

A wrong secret is MachineError::Refused with error invalid_client.

The API verifies the token like a user’s: see Protect an API. With the Rust SDK, user.is_machine() is true and user.id() is the client’s client_id.

Rotating the secret in Clients (or with POST /v1/environments/:id/clients/:client/secret, admin) shows a new secret once. The old one stops working at once, so put the new one in your deployment’s secrets straight away; MachineClient gets invalid_client until it has it. See Clients.