Machine access

​

When to use machine access

• Provision or update users via the Builder API.
• Mint user-scoped JWTs for end-users already known to your system.
• Read aggregated usage data from the Usage API.
• Complete a device authorization on behalf of a user (RFC 8693 token exchange).

​

Prerequisites

• A confidential M2M client (m2m_… id and pmth_cs_… secret). See Client model.
• The M2M client has been granted the scopes required by the endpoint you are calling.

export BASE_URL="https://your-pymthouse.example"
export M2M_ID="m2m_yourClientId"
export M2M_SECRET="pmth_cs_yourSecret"

​

Option A: Client credentials grant

​

1. Obtain a machine token

MACHINE_TOKEN=$(curl -sS \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${M2M_ID}" \
  -d "client_secret=${M2M_SECRET}" \
  -d "scope=users:write users:token" \
  "${BASE_URL}/api/v1/oidc/token" | jq -r '.access_token')

​

2. Call the Builder API with Bearer auth

curl -sS \
  -H "Authorization: Bearer ${MACHINE_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "externalUserId": "user-123", "email": "alice@example.com", "status": "active" }' \
  "${BASE_URL}/api/v1/apps/${PUBLIC_CLIENT_ID}/users"

​

Option B: HTTP Basic auth

curl -sS \
  -u "${M2M_ID}:${M2M_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{ "externalUserId": "user-123", "email": "alice@example.com", "status": "active" }' \
  "${BASE_URL}/api/v1/apps/${PUBLIC_CLIENT_ID}/users"

​

Choosing between Bearer and Basic

​

Error responses

​

Rotating client secrets

1. Update the secret in your backend’s secret manager.
2. Redeploy or restart the service.
3. Do not rotate the public client secret — public clients must remain secretless.

​

Key design decisions

1. Basic auth is supported alongside Bearer. Confidential server-to-server clients are common in automation tooling where adding a token exchange step adds operational friction. Supporting both modes simplifies bootstrapping and scripting without compromising security, since the credential type (M2M secret) carries the same privilege either way.
2. Tenant boundary on path, not query parameter. Enforcing clientId as a URL path segment rather than a query parameter makes the tenant scope visible and cache-key-safe. The route handler resolves the OAuth client_id to an internal record before any query, keeping the public API free of internal IDs.
3. Short-lived machine tokens, not long-lived API keys. Using the standard client credentials flow means PymtHouse does not need a separate API-key issuance system. Short lifetimes limit the blast radius of a compromised token without requiring explicit revocation infrastructure.

​

Implementation tasks

• Store M2M_ID and M2M_SECRET in your backend secret manager (e.g., HashiCorp Vault, AWS Secrets Manager, Vercel environment variables). Do not commit them to source control.
• Implement a simple in-process token cache: acquire a machine token once per request batch, reuse it, and let it expire naturally rather than building explicit refresh logic.
• For HTTP Basic auth calls, ensure your HTTP client encodes the credentials correctly (base64(client_id + ":" + client_secret)). Most libraries handle this via a auth or user/password field.
• Test that Basic auth calls to a different app’s clientId return 404, not 403 — this verifies that the tenant boundary is enforced, not just that the credentials are valid.