Skip to main content
Use a linked OAuth client and an approved resource grant to authenticate your agent. This is the minimal single-client integration. Registration, grant approval and secure configuration are prerequisites. Applications that separate credentials for sensitive workloads need an explicitly configured client for each workload, not necessarily one client per API endpoint. Initialize clients once and reuse them for their approved operations; do not create a new client for every call.

​
1. Establish authority

Register an agent and link an OAuth machine client to it. Register the client’s public JWK, complete proof of possession, and obtain an approved grant for the exact resource and scopes you will request. Linking a client alone grants no access. Use the same organization and environment throughout. Keep the private key in your application environment. Do not upload it to the portal. The same workflow supports sandbox and production, subject to server eligibility checks.

​
2. Configure the process

Set these environment variables through your shell or deployment secret manager. If you use a .env file, your application must explicitly load it; the SDK does not search for one. Replace placeholders with your actual configuration.
Using two clients in the same application, including clients linked to the same agent? Follow the complete two-client example. Choose a separate prefix for each configuration and pass it to MachineAgent.from_env(prefix).

​
Alternative: client-secret authentication

For a client registered with client-secret authentication, use this process configuration instead of the signing-key settings. The resource grant and server policy checks still apply. Use the authentication method approved for your client.

​
3. Install and call the protected resource

Replace the example URL with your protected resource. The SDK exchanges a signed client assertion for a scoped access token, caches it until near expiry, and attaches it to resource requests. Confirm the protected API verifies the expected issuer, audience and scopes.

​
Diagnose a refusal

  • Missing configuration: check the selected prefix and all required variables.
  • Authentication refused: check client status, registered key, assertion audience and token endpoint in the same environment.
  • Resource/scope refused: check the approved grant, resource, scopes and linked agent.
  • Rate limited: respect MudraIDRateLimitedError.retry_after_seconds when supplied.
  • Billing refusal: review the server’s plan/eligibility requirement.
POST/PATCH requests with uncertain outcomes are not blindly replayed. Reconcile an ambiguous operation before retrying; an idempotency key helps only when the resource server actually deduplicates it. See Configuration and Handle errors.