Skip to main content
When agents are local and short-lived, open access can feel harmless. The moment an agent becomes a real network participant, that assumption breaks. You need a way to prove who is calling, what they are allowed to do, and whether a token should still be trusted when it reaches the API boundary. Without authentication, access control becomes fragile. Protected methods can be exposed too broadly, tokens cannot be validated consistently, and the agent loses a clean trust boundary between caller and execution.

​
Why Authentication Matters

In an agent network, trust should not depend on a hidden allowlist or a private convention. A caller needs a standard way to obtain credentials, present them, and be checked before access is granted.
Unauthenticated accessBindu authentication
Easy for local testingSafer for production access control
No formal identity at request timeOAuth2 tokens define who is calling
Hard to apply consistent policyHydra provides a standard token workflow
Weak boundary between caller and APIRequests are checked before protected actions run
Fine for experimentsBetter for networked and production agents
That is the shift: Bindu uses Ory Hydra so agents can participate in a standard OAuth2 flow, obtain access tokens, and enforce protected access with a clear trust boundary.
If an agent is exposed beyond local development, it should not rely on obscurity for security. It should be able to verify who is calling before sensitive work begins.

​
How Bindu Authentication Works

Bindu uses Ory Hydra as its authentication backend for production deployments. Authentication is optional, so you can still run agents without it for development and testing.

​
The Authentication Model

Bindu uses a straightforward token flow: 
register client -> obtain token -> call API with bearer token
Example flow: 
agent identity -> Hydra client -> access token -> authenticated request
The model is easy to reason about:
  • The agent is registered as an OAuth client.
  • Hydra issues a client_secret.
  • The caller exchanges credentials for an access token.
  • The token is sent with the API request and validated before access is granted.

Standard

Authentication follows an OAuth2 client credentials flow instead of a custom ad hoc scheme.

Scoped

Access tokens carry explicit scopes such as agent:read and agent:write.

Verifiable

Tokens can be introspected against Hydra so access decisions are made with a trusted source of truth.

​
The Lifecycle: Register, Mint, Verify

Let’s break the flow down first, then walk through each stage. What this means is simple: Bindu turns agent access into a repeatable trust flow instead of a custom one-off secret exchange.
1

Register

During bindufy, the agent is registered with Hydra as an OAuth client using the full DID string as the client_id. Hydra returns the client_secret needed for future token requests.Bindu saves these OAuth credentials to oauth_credentials.json inside the agent’s credentials directory, which defaults to .bindu/. The file is a map keyed by agent DID.
2

Mint

When you deploy your agent, obtain an access token using the OAuth2 client credentials flow.Bindu registers Hydra clients with token_endpoint_auth_method=client_secret_post, which means token requests should send the client_id and client_secret in the form body.
curl -X POST https://hydra.getbindu.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<YOUR_AGENT_DID>" \
  -d "client_secret=<YOUR_CLIENT_SECRET>" \
  -d "scope=openid offline agent:read agent:write"
Your credentials come from two places:
  • Agent DID: Found in the agent card at /.well-known/agent.json
  • Client Secret: Typically located in .bindu/oauth_credentials.json
3

Verify

When AUTH__ENABLED=true, Bindu installs HydraMiddleware on the agent server. For non-public endpoints, it intercepts the request, reads the bearer token from the Authorization header, and introspects that token against the Hydra Admin API.
curl --location "http://localhost:3773/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <your-access-token>" \
  --data "<valid A2A JSON-RPC request body>"
If AUTH__REQUIRE_PERMISSIONS=true, Bindu will also enforce method-specific scopes like agent:read and agent:write before the request reaches the handler.Optional: if X-DID, X-DID-Signature, and X-DID-Timestamp headers are present, Bindu can perform an additional cryptographic DID-signature verification step on the request body.

​
Configuration

Authentication should be easy to enable when you need it and easy to avoid when you do not. Bindu keeps the configuration surface intentionally small.

​
Environment Variables

Configure Hydra via environment variables: 
# Enable authentication
AUTH__ENABLED=true

# Set provider to Hydra (only supported provider)
AUTH__PROVIDER=hydra

# Hydra endpoints
HYDRA__ADMIN_URL=https://hydra-admin.getbindu.com
HYDRA__PUBLIC_URL=https://hydra.getbindu.com

# Optional: enforce strict method-level scopes
AUTH__REQUIRE_PERMISSIONS=false
Bindu uses Hydra’s Public API for token minting at /oauth2/token and Hydra’s Admin API for token introspection at /admin/oauth2/introspect.

​
Agent Configuration

No additional configuration is needed in your agent code. Authentication is handled automatically when the required environment variables are set. This is deliberate. Your agent definition stays focused on behavior, while the environment decides whether the runtime should enforce authentication.

​
Standards

OAuth2

Hydra uses the OAuth2 client credentials flow so agents can obtain tokens through a standard authentication model.

Ory Hydra

Hydra acts as the centralized authority for client registration, token minting, and token validation.

Scoped Access

Scopes like openid, offline, agent:read, and agent:write keep access explicit.

​
Getting Access Tokens

There are two practical ways to get a token depending on whether you want direct API control or a simpler testing workflow.

​
Method 1: API Request

Use the OAuth2 token endpoint directly when you want explicit control over the authentication flow: 
curl -X POST https://hydra.getbindu.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<YOUR_AGENT_DID>" \
  -d "client_secret=<YOUR_CLIENT_SECRET>" \
  -d "scope=openid offline agent:read agent:write"

​
Method 2: UI

Use the frontend UI to obtain tokens more easily during testing:
  1. Start the frontend: 
    cd frontend
npm run dev
  2. Navigate to Settings -> Authentication.
  3. Enter your CLIENT_SECRET, typically found in .bindu/oauth_credentials.json.
  4. Click Get Access Token.
  5. Copy the generated token.
The difference is simple: the API path is better for explicit automation, while the UI path is easier when you are manually testing.

​
The Value of Authenticated Access

Authentication only matters if it creates a cleaner and safer trust boundary. This model gives you:
  • Controlled access: protected methods are no longer open by default.
  • Standardized identity checks: tokens flow through a well-known OAuth2 model.
  • Clearer trust boundaries: the API can validate who is calling before sensitive work starts.
This is the point of the whole model: as agents move into real environments, access should become explicit and inspectable instead of informal and fragile.

​
Real-World Use Cases

When an agent is exposed publicly or shared across teams, Hydra-backed authentication ensures only token-bearing callers can reach protected functionality.
AUTH__ENABLED=true
AUTH__PROVIDER=hydra
If one service or agent needs to call another automatically, the client credentials flow gives it a clean way to request an access token programmatically.
curl -X POST https://hydra.getbindu.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<YOUR_AGENT_DID>" \
  -d "client_secret=<YOUR_CLIENT_SECRET>" \
  -d "scope=openid offline agent:read agent:write"
During local or pre-production testing, the frontend UI gives developers a faster path to token generation without manually crafting every request.
cd frontend
npm run dev

​
Security Best Practices

Keep Client Secrets Private

Treat the generated OAuth credentials file, typically .bindu/oauth_credentials.json, as sensitive material and never expose the client_secret publicly.

Use Scopes Deliberately

Request only the scopes you actually need so access remains narrow and explicit.
Sunflower LogoBindu helps agents prove who they are - each one independent, making it easy to verify and trust across the Internet of Agents.