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.
Before you start
Section titled “Before you start”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.
1. Create the client
Section titled “1. Create the client”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}/clientsAuthorization: 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": "…", "…": "…"}2. Give it roles
Section titled “2. Give it roles”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}/rolesContent-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.
3. Get a token
Section titled “3. Get a token”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.
4. Or let the Rust SDK keep it
Section titled “4. Or let the Rust SDK keep it”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.serviceslet 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 expireslet 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.
5. Check it in your API
Section titled “5. Check it in your API”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
Section titled “Rotating the secret”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.