Authentication
MachineAuth uses OAuth 2.0 Client Credentials flow for agent authentication.
How It Works
- Create an Agent — Admin creates an agent, receives
client_idandclient_secret - Request Token — Agent exchanges credentials for a JWT access token
- Use Token — Agent uses Bearer token in Authorization header
- Verify Token — Resource server verifies token using JWKS
OAuth 2.0 Client Credentials Flow
┌─────────┐ ┌─────────────┐ ┌──────────────┐
│ Agent │────▶│ MachineAuth │────▶│ Resource API │
│ │ │ (OAuth) │ │ │
└─────────┘ └─────────────┘ └──────────────┘
│ │ │
│ 1. POST │ │
│ /oauth/token │ │
│ (credentials) │ │
│───────────────▶│ │
│ │ │
│ 2. JWT Token │ │
│◀───────────────│ │
│ │ │
│ 3. GET /api │ │
│ Authorization: │ │
│ Bearer JWT │ │
│─────────────────────────────────────▶│
│ │ │
│ 4. Verify JWKS │ │
│◀───────────────│─────────────────────│
Token Request
curl -X POST http://localhost:8080/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "cid_abc123...",
"client_secret": "cs_secret...",
"scope": "read write"
}'
Token Response
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read write",
"refresh_token": "rt_xyz789..."
}
Scopes
Agents can be assigned scopes that limit their permissions:
| Scope | Description |
|-------|-------------|
| read | Read-only access |
| write | Write access |
| admin | Administrative access |
Request specific scopes:
{
"scope": "read write"
}
If no scope requested, all agent scopes are granted.
Token Introspection
Verify a token without validating locally:
curl -X POST http://localhost:8080/oauth/introspect \
-d "token=YOUR_ACCESS_TOKEN"
Response (valid token):
{
"active": true,
"scope": "read write",
"client_id": "cid_abc123...",
"exp": 1709308800,
"iat": 1709305200,
"token_type": "Bearer"
}
Response (invalid/expired):
{
"active": false,
"reason": "expired"
}
Token Revocation
Revoke a token immediately:
curl -X POST http://localhost:8080/oauth/revoke \
-d "token=YOUR_ACCESS_TOKEN"