Prerequisites
- An Authdog project and environment.
- A machine-to-machine application created in the Authdog console.
- Client ID and client secret captured when the application is created. The secret is shown once.
- A trusted server, worker, job, or agent runtime. Client credentials must never be placed in browser code.
- An API or MCP server that validates bearer tokens and enforces authorization.
Use a separate M2M application for each workload and environment. This keeps development and production credentials independent and lets one compromised workload be replaced without rotating unrelated automation.
Discover the environment’s token endpoint from its OIDC metadata instead of hard-coding a deployment origin. Repository documentation identifies Authdog’s token path as /oauth2/token, but discovery also accommodates environment custom domains.
Implementation
Request a short-lived access token from the trusted agent runtime. Send client credentials with HTTP Basic authentication and use an application/x-www-form-urlencoded body:
curl -X POST "$TOKEN_ENDPOINT" \
-u "$AUTHDOG_CLIENT_ID:$AUTHDOG_CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials"A successful response contains access_token, token_type, expires_in, and scope client_credentials. Client-credentials exchanges do not return a refresh token. Refresh by repeating the exchange before the access token expires.
Send the token only to the intended protected service:
Authorization: Bearer <access_token>The receiving service must validate the token before executing agent-selected work. For an MCP service, the repository’s examples/mcp-auth-sample performs authentication before the MCP transport runs. Its supporting packages/mcp-sdk code verifies JWT signatures through JWKS, can check issuer and audience, and can require scopes. The sample then attaches verified claims to request context and applies an additional mcp:admin scope check inside its admin_echo tool.
That sequence provides a useful agent boundary:
- Authenticate every request before dispatch.
- Reject a token with the wrong issuer or audience.
- Require a baseline scope for the service.
- Apply narrower checks again at sensitive tool or operation boundaries.
- Treat authenticated identity as input to authorization, not as blanket permission.
Cache an access token only in trusted process memory and only until shortly before expires_in. When many agent instances refresh concurrently, add jitter so they do not all request tokens at once.
Security considerations
Store client secrets in a secret manager. Never commit them, expose them in frontend bundles, include them in prompts, write them to command history, or emit them to logs. Access tokens are bearer credentials and require the same redaction discipline.
Use least privilege around every callable action. Repository examples separate a service-wide scope such as mcp:invoke from the tool-specific mcp:admin scope. A valid token should identify the agent but should not automatically authorize all tools, tenants, environments, or records.
Do not give unattended automation a human user’s cookie or personal token. Authdog’s M2M flow exists specifically for non-human workloads. Service accounts are another organization-owned automation model exposed by the Authdog API, while personal access tokens remain attached to a person and are intended for that person’s scripts or developer tooling.
Record non-secret correlation data such as client ID and workload name in audit context, but redact client secrets and complete access tokens. On suspected exposure, stop using the client and replace its credentials rather than waiting for issued tokens to expire.
Keep environment boundaries explicit. Authdog clients and signing context are environment-scoped, so validate development and production separately and never share production credentials with development agents.
Validation checklist
- Agent obtains a token with
client_credentials, without a browser or user session. - Invalid client credentials are rejected by the token endpoint.
- Protected service rejects a missing bearer token.
- Protected service rejects expired, malformed, wrong-issuer, or wrong-audience tokens.
- Baseline scope failure prevents request dispatch.
- Sensitive operations enforce their own narrower scope.
- Development token does not grant production access.
- Logs contain workload identifiers but no secrets or complete tokens.
- Token refresh repeats the client-credentials exchange; code does not expect a refresh token.
- Credential replacement procedure is documented and tested.
Troubleshooting
If token exchange fails, confirm the client is active, uses the expected authentication method, has the correct secret, and is authorized for client_credentials. Use OIDC discovery to verify the token endpoint.
If a protected service returns 401, inspect verification configuration: issuer, JWKS URI, audience, token expiry, and bearer-header formatting. If it returns 403, authentication likely succeeded but a required service or operation scope is missing.
If failures occur only across environments, verify the agent is using the client and endpoint for the same Authdog environment as the protected service. Do not work around an audience or issuer mismatch by disabling validation.
Next steps
- Read Machine identity for M2M applications, service accounts, and personal access tokens.
- Read Backend requests for trusted server validation.
- Read Authorization before assigning agent permissions.
- Use
examples/mcp-auth-sampleandpackages/mcp-sdkwhen the protected agent interface is MCP.