---
title: Authenticate an agent with Honen
description: OAuth 2.0 with PKCE for Honen MCP plus bearer credential guidance for the Connector HTTP API.
canonical: https://honen.com/auth.md
last-updated: 2026-08-31
---

# Authenticate an agent with Honen

Honen uses user-authorized OAuth 2.0 with PKCE for MCP access. The separate Connector HTTP API uses a workspace-issued Connector secret or constrained child token. Do not collect a user's Honen password, embed a bearer token in a plugin, or send a token to any origin other than the Honen resource server.

## Discover

Start with RFC 9728 protected-resource metadata:

```text
https://honen.com/.well-known/oauth-protected-resource
```

Its `authorization_servers` value points to RFC 8414 metadata at:

```text
https://honen.com/.well-known/oauth-authorization-server
```

Read these documents at connection time. They are the source of truth for authorization, token, dynamic registration, scopes, and PKCE support.

## Pick a method

Use the OAuth authorization-code grant with PKCE `S256`. Honen does not support password grants, embedded service credentials, anonymous mutation access, or a separate WorkOS `agent_auth` identity-assertion flow. The signed-in user is the authorizing identity.

For a server-to-server Connector HTTP API integration, use a Connector credential created by an authorized workspace administrator instead of the MCP OAuth flow. Apply the least-privilege Connector policy and keep the `hn_` bearer secret outside source code and agent prompts.

## Register

Register a public OAuth client with the `registration_endpoint` advertised by the authorization-server metadata. Supply the client's redirect URI. The returned `client_id` is public client metadata, not a secret.

## Claim

Honen does not expose a separate `claim_endpoint`. The user claims and approves the connection by signing in at the advertised `authorization_endpoint`. Open that URL in the user's browser with the registered `client_id`, exact `redirect_uri`, requested `scope`, random `state`, PKCE `code_challenge`, and `code_challenge_method=S256`.

The `agent_auth`, `identity_endpoint`, `identity_assertion`, `service_auth`, and ID-JAG token type `urn:ietf:params:oauth:token-type:id-jag` belong to a different optional authentication profile and are not currently accepted by Honen.

## Exchange

After authorization, verify `state`, then send the returned code to the advertised `token_endpoint` with the original PKCE `code_verifier`, `client_id`, `redirect_uri`, and `grant_type=authorization_code`. The response contains an `access_token`, token type, expiry, granted scopes, and a refresh token when available.

## Use the access_token

For MCP, connect to:

```text
https://honen.com/api/mcp/mcp
```

Send the token only in the HTTP header:

```http
Authorization: Bearer <access_token>
```

The token is scoped to the authorizing user and Honen workspace permissions. Tool availability and each operation's authorization checks remain authoritative.

For the Connector HTTP API described at `https://honen.com/openapi.json`, send its workspace-issued Connector secret or child token in the same `Authorization: Bearer` header. An MCP OAuth access token and a Connector credential are not interchangeable.

## Errors

Follow the HTTP status and structured JSON error body. A `401` response means the token is missing, invalid, or expired; read its `WWW-Authenticate` header and repeat discovery. A `403` means the authenticated user or granted scope cannot perform the operation. A `404` can intentionally conceal a resource outside the user's workspace. A `429` requires backoff according to `Retry-After`.

Never retry authorization failures as mutations, and never substitute a resource identifier from another workspace.

## Revocation

Honen does not currently advertise a token revocation endpoint. Users can remove an authorized connection from their Honen workspace settings. Clients should delete local access and refresh tokens when a user disconnects, when refresh fails, or when the server returns an unrecoverable authorization error.