OAuth Agent Grants Profile

​

Hosted endpoints

​

Security profile

• PAR is required and request URIs expire after 90 seconds.
• Authorization uses the code flow with PKCE S256 and RFC 9207 iss.
• DPoP proofs bind PAR, code exchange, refresh, token exchange, revocation, and protected-resource requests to the registered Agent Key.
• Access tokens expire after five minutes and carry standard client_id, scope, aud, and cnf.jkt claims.
• Refresh tokens rotate on every use. Reuse revokes the complete token family.
• RFC 8693 token exchange only permits exact-scope attenuation for the same client instance, sender key, and resource.
• RFC 7009 revocation does not reveal whether the presented token existed.
• A registered Agent Key cannot be shared by another Agent Client Instance.

​

Authorization flow

1. Register an agent with an exact redirect URI, resource URI, scope set, and public Agent Key through POST /v1/agents.
2. Discover and validate the authorization-server metadata.
3. Generate a high-entropy state, PKCE verifier and challenge, and a DPoP proof from the registered private key.
4. Push the complete request to /oauth/par.
5. Open /oauth/authorize with only client_id and the returned request_uri.
6. In live mode, the principal selects an account and verifies the decision with a registered passkey. Sandbox auto-approval remains isolated from live conformance deployments.
7. Validate the callback URI, exact state, and exact response iss before exchanging the code.
8. Exchange the code with the PKCE verifier and a fresh DPoP proof.
9. Present the access token using Authorization: DPoP <token> and a proof containing the matching ath claim.

​

TypeScript client

import { OAuthAgentClient } from '@grantex/sdk';

const client = await OAuthAgentClient.create({
  issuer: 'https://grantex.dev',
  clientId: process.env.GRANTEX_AGENT_ID!,
  redirectUri: 'https://client.example/callback',
  resource: 'https://grantex.dev/oauth/resource',
  privateKey,
  publicJwk,
});

const pending = await client.beginAuthorization({
  scopes: ['grantex.resource.read'],
});

// Redirect the principal to pending.authorizationUrl. On return:
const tokens = await client.completeAuthorization(callbackUrl);
const response = await client.fetch(
  'https://grantex.dev/oauth/resource',
  tokens.access_token,
);

​

Live deployment requirements

• Terminate external traffic with HTTPS and configure the exact public issuer.
• Keep PostgreSQL and Redis highly available; replay and revocation checks fail closed when required state is unavailable.
• Enroll and identity-proof live principal passkeys before authorization.
• Register exact redirect and resource URIs; wildcards are not accepted.
• Monitor authorization, refresh-family replay, revocation, and migration failures without logging tokens or DPoP proofs.
• Check existing Agent Key registrations before applying the uniqueness migration to a database created by an older release.

​

Evidence and limits