> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate and authorize

> Connect verified caller identity to authoritative resource ownership.

The current text HTTP and Socket.IO adapters require an explicit security mode. Use `local` for trusted local applications. Use `authenticated` for hosted applications, with host-owned identity resolution and resource authorization.

## Follow one request

1. Your authentication layer verifies credentials. It must reject invalid credentials before Agent execution.
2. `resolveIdentity` derives the user and optional tenant from those verified claims.
3. `authorizeResource` checks the operation against authoritative resource ownership.
4. Tools use that identity to authorize access to domain records such as orders.
5. The result returns through the authorized session and request boundary.

For HTTP, `resolveIdentity` receives the verified value on `req.user`. For Socket.IO, the gateway hook resolves identity from connection data according to the configured contract. Do not construct that identity from unverified body fields or socket claims.

## Implement the two ownership cases

| Operation | Required application behavior |
| - | - |
| `session:create` | Atomically bind the generated session ID to the verified user/tenant before returning true |
| `session:use` | Load the existing owner binding and permit only the correct user/tenant |

Deny unknown or ownerless sessions. A database with a unique session key can enforce atomic creation; a read followed by an unprotected write can race. If identity or owner storage is unavailable, fail closed.

The router returns a new HTTP session ID in `X-Agentium-Session-Id`. Your client can use that ID for follow-ups. A session ID is a reference, not a credential.

## Authorize more than conversations

Run lookup, checkpoint restore, approval decisions, schedules, and administration have their own operations. Grant only the routes your application uses. For an approval, verify the pending action's owner and the caller's authority to approve it; possessing a request ID is insufficient.

JWT scopes express permissions such as a broad ability to use a route. They do not establish ownership of a particular order or conversation. Enforce domain ownership inside tools even when the surrounding session was authorized.

## Run the ownership exercise

Start the [complete API project](/examples/authenticated-api), then run its [four request checks](/examples/authenticated-api#exercise-the-boundary). The fixture uses loopback HTTP and known demo tokens: no token yields 401, Alice creates and reuses a session with 200, and Bob using Alice's ID receives 403. Sending a conflicting body identity also receives 403.

Repeat those assertions after replacing the token map and ownership map with your real authentication and store. The local demo proves the hook contract; restart and concurrent-creation tests must exercise your durable owner store.

## Verify the integration

| Request | Expected outcome |
| - | - |
| Missing or invalid credentials | Rejected before model or tool work |
| User A creates a conversation | Owner binding committed before execution |
| User A resumes that conversation | Allowed |
| User B supplies A's session ID | Rejected |
| Body claims a different user/tenant | Rejected |
| Owner lookup fails | Rejected; no fallback to local mode |
| User B attempts to approve A's refund | Rejected; the decision remains unchanged |

Run these checks at the HTTP/socket boundary and against the underlying tool's data access. See [Express](/transport/express), [Socket.IO](/transport/socketio), [JWT/RBAC](/transport/jwt-rbac), and [execution policy](/agents/execution-policy) for the respective contracts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.