agentleFS
Atlas-AuthorizationAtlas-Authorization/atlas-claude-skills/skills/atlas-machines/SKILL.md

atlas-machines

Skill0 starsChanged 42 days agoMITView on GitHub

Set up machine-to-machine (M2M) / device identities with Atlas (atlasauth.net) — mint an enrolment token, enroll a device with its public key (public_key_pem / device_key), run the challenge→sign→token ceremony to get a short machine JWT (token_use:m2m), and verify it. Covers the device registry, approval gating, plan/token device caps, and the distinct refusal codes. Use when the user needs service accounts, IoT/device auth, agent credentials, CLI/daemon auth, or M2M tokens with Atlas.

The file

Files
SKILL.md

Atlas machines (M2M / device identities)

Two shapes exist: named machine identities (a service account with a secret mk_…) and the device-enrolment keypair ceremony (a device proves possession of a private key to mint short JWTs). This skill covers the keypair ceremony, which is the self-serve, LAN/offline-friendly path.

Management calls (mint tokens, list/revoke devices) use sk_… against https://api.atlasauth.net. The device self-serve routes are PUBLIC (authenticated by the presented credential).

1. Mint an enrolment token (operator, sk_…)

POST /v1/machine_enrolment_tokens → returns the token secret once (201). Body (all optional):

  • organization_id — bind the device to an org (omit for the instance-wide pool).
  • max_uses — how many devices it can enroll.
  • expires_in_seconds — TTL.
  • requires_approval — if true, enrolled devices land pending until approved.
  • owner_user_id, data — trusted metadata carried to enrolment.

List with GET /v1/machine_enrolment_tokens, delete with DELETE /v1/machine_enrolment_tokens/:id.

2. Enroll a device (device, public)

The device generates an asymmetric keypair locally and sends its public key: POST /v1/machines/enroll →

{
  "enrolment_token": "<the token secret>",
  "public_key_pem": "-----BEGIN PUBLIC KEY----- ... (SPKI PEM)",
  "name": "edge-node-01",
  "metadata": { "hostname": "...", "os": "...", "app_version": "..." },
  "device_key": "stable-per-device-id"
}

Returns 201 with the machine id; status is pending when the token requires_approval, else active. device_key makes it a RE-ENROLMENT: any live machine with the same device_key is superseded (emitting machine.revoked reason superseded) BEFORE the cap check, so a device reuses its own slot. Enrolment is capped at the SMALLER of the token's max_uses/max_machines and the org plan's device limit (entitlement max_machines/max_devices); exceeding either is a 403 naming the bound hit.

Variant: POST /v1/machines/redeem spends one use WITHOUT registering a machine (returns the token's trusted data for out-of-band provisioning).

3. Challenge → sign → token (device, public)

POST /v1/machines/challenge   { "machine_id": "mch_..." }         -> { nonce }
# device signs the nonce with its PRIVATE key
POST /v1/machines/token       { "machine_id", "nonce", "signature" } -> { token }  // a short JWT, token_use:m2m, JWKS-signed

The device then calls your API with Authorization: Bearer <m2m JWT>.

4. Verify an m2m token (your API)

It is a JWKS-signed RS256 JWT with token_use: 'm2m' — verify it locally against the instance JWKS exactly like a session (see atlas-verify-backend), just expect token_use:'m2m' rather than 'session'. To verify a named-machine SECRET (mk_…) instead: POST /v1/m2m_tokens/verify with sk_… → { valid, machine_id? }.

5. Device registry lifecycle (operator, sk_…)

  • GET /v1/machines — list/filter by status, hostname, owner_user_id, organization_id, metadata (jsonb containment); keyset pagination.
  • POST /v1/machines/:id/approve — pending → active (for approval-gated tokens).
  • POST /v1/machines/:id/revoke — key stops minting immediately (record kept).
  • POST /v1/machines/:id/rotate_key — register a new public_key_pem; old private key stops verifying.
  • PATCH /v1/machines/:id/metadata — merge hostname/os/app_version/last_seen_at.
  • DELETE /v1/machines/:id.

Distinct refusal codes (all 401, on enroll/redeem)

  • ENROLMENT_TOKEN_INVALID — no matching token (also the generic for a token that hashes to no row — not a probing oracle).
  • ENROLMENT_TOKEN_EXPIRED — the token's TTL passed.
  • ENROLMENT_TOKEN_EXHAUSTED — all uses spent. A device-cap overflow is a 403 naming whether the token cap or the plan/org device limit was hit. Every error also carries a docs_url (https://atlasauth.net/docs/errors/<code>).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.