HexaEight and OAuth

OAuth and HexaEight answer different questions, and they work side by side.

	OAuth	HexaEight
The question it answers	may this application act for this user, within these scopes?	who sent this message, and may they reach this agent?
What it issues	tokens, from your identity provider	identities — for people from the Authenticator, for agents bound to a machine
The message itself	protected by TLS, hop by hop	encrypted end to end between the two identities
Where it shines	sign-in, delegation with scopes, central revocation, familiar tooling	messages that pass through other systems unread, agents that have never met, no provider in the path of a message

Most deployments use both. Your identity provider keeps doing what it already does — sign-in, provisioning, revocation — and HexaEight carries the messages between agents and proves who sent each one.

Where they meet

Your company vouches for your agent. Link the agent to your company’s OAuth app, and other agents check on every message that your company still stands behind it. Below.
Your agent calls APIs that expect OAuth. An API you put behind an agent can use its own OAuth client. Below.
Your API learns who asked. When another agent’s request reaches your API through your agent, the call says which agent asked. Below.

Link your agent to your company’s OAuth app

What you get: every agent your agent writes to can check, on every message, that your company still stands behind it. Disable the app in your identity provider, and other agents refuse this one once the token it holds is used up — within an hour by default.

How it works

Your agent gets a token from your company’s OAuth app (client credentials) and carries it inside each encrypted message it sends to another agent.
The receiving agent looks up a DNS record on your agent’s name, checks the token against your identity provider’s published signing keys, and checks a rule of its own that names your agent and your client ID.
The token must grant nothing. It proves only that the agent is still authorised — no app roles, no API permissions, no scope beyond the one made for this proof. A token that grants more is refused and never sent.
The receiving agent removes the token before anything else sees the message, and records every check in its audit trail.
Once a receiving agent has seen your agent linked, it keeps requiring the token, even if a later DNS lookup fails.

On the sending agent

In your identity provider, create an app for this proof, with a dedicated audience that is not a real API — for example api://hexaeight-proof.
From the agent’s folder (on macOS the binary is hexaeight-agent-osx-arm64):
Terminal window
```
./hexaeight-agent-linux-x64 hexaeight-agent.json oauth-link set
```
It asks for the issuer, the client ID, the audience and the secret — the secret at a prompt that does not show it. It fetches a test token first, and saves nothing if that token grants anything.
Publish the DNS record it prints, as a TXT record on your agent’s name:
```
hexaeight-oauth=v1; iss=<issuer>; client_id=<client id>; aud=<audience>
```

Check it:

./hexaeight-agent-linux-x64 hexaeight-agent.json oauth-link status
./hexaeight-agent-linux-x64 hexaeight-agent.json oauth-link dns

On each receiving agent, allow your agent with that client ID — by its exact name, or a domain such as *.yourcompany.com (a bare * never counts):

./hexaeight-agent-linux-x64 hexaeight-agent.json --add-rule "<your agent>,clientid:<client id>,inbound,allow"

Settings

Command	What it sets
`oauth-link renew <1-60>`	how often the sending agent fetches a new token — 60 minutes by default
`oauth-link max-age <5-120>`	on a receiving agent: the oldest token it accepts — 120 minutes by default
`oauth-link off` · `on`	stop or resume sending the token
`oauth-link except add <agent>`	an agent the token is never sent to
`oauth-link test`	fetch a token now and check it

APIs that expect OAuth

When you put an API behind an agent, the route can carry its own OAuth client: the agent fetches a token with client credentials and sends it with every call.

./hexaeight-agent-linux-x64 hexaeight-agent.json add-api --name <route> --url <api address> \
    --oauth-issuer <issuer> --oauth-client-id <client id> --oauth-scope <scope>

The secret is typed at a prompt that does not show it. The client is tried before the route is saved, and a call refused with 401 is retried once with a fresh token. For an API that takes a key in a header instead, --secret-header asks for the header’s value the same way.

Your API learns who asked

When another agent’s request reaches your API through your agent, the call carries headers that say who asked: X-HexaEight-Caller (the agent that asked), X-HexaEight-Caller-ClientId (its OAuth client, when it is linked), X-HexaEight-Forwarded-By (an agent that passed the request on) and X-HexaEight-Request-Id, which ties the call to the same request in every agent’s audit trail.

These headers come only from your agent: any X-HexaEight-* header that arrives from outside is removed first.