OAuth for hosted agents
How claude.ai, ChatGPT, and other hosted connectors sign in to Joring without an API key.
Some agents cannot hold an API key: a custom connector in claude.ai or a connector in ChatGPT signs in with OAuth instead. Joring runs an OAuth 2.1 authorization server for exactly that. You never configure it; you approve the connection once, in your browser, and can disconnect it any time.
Connect a hosted agent
Add the MCP server in the agent
Give it https://api.joring.ai/mcp. In claude.ai that is Settings →
Connectors → Add custom connector; in ChatGPT it is a connector in
developer mode. No client id or secret is needed.
Sign in and choose a workspace
The agent opens joring.ai. Sign in if you are not already, check the agent's name and where it returns to, pick the workspace it will work in, and choose Connect.
Use it like any other agent
The connector gets the tools listed in MCP server for the scopes you approved. Every write shows in the audit log attributed to the connector and to you.
What you are approving
The consent page shows:
- Who is asking. "Published by its vendor" means the agent's identity came from a metadata document on the vendor's own domain. "Self-registered" means the agent registered itself, so Joring cannot verify who published it; only continue if you started the connection yourself.
- What it can do. Read, write, and publish trails, as API key scopes describe them.
- Where. One workspace where you hold the Trail author role and API access is turned on, or the Joring catalog for Joring staff.
A connection acts as you. If you lose the role or leave the workspace, it stops working.
Disconnecting
Settings → API keys → Connected agents lists your connections with Disconnect. Admins, IT admins, and Security admins can switch to All connections in this workspace and disconnect anyone's. Disconnecting revokes every token the connection holds, immediately.
For people building a client
Joring implements OAuth 2.1 with PKCE (S256), the discovery documents MCP clients expect, and both ways an MCP client can identify itself:
| Authorization server metadata | https://api.joring.ai/.well-known/oauth-authorization-server (RFC 8414) |
| Protected resource metadata | https://api.joring.ai/.well-known/oauth-protected-resource/mcp (RFC 9728), also named in the WWW-Authenticate header of a 401 from /mcp |
| Client identity | A client ID metadata document URL (client_id is an https URL that serves your client metadata), or dynamic registration at POST /oauth2/register (RFC 7591, public clients only) |
| Grants | authorization_code with PKCE, refresh_token; refresh tokens rotate and reuse revokes the family |
| Resource | Send resource=https://api.joring.ai/mcp (RFC 8707); tokens are bound to it |
| Scopes | trails:read, trails:write, trails:publish; omit scope to request all three |
| Redirect URIs | https:// anywhere, or http:// on localhost, 127.0.0.1, or [::1] for a CLI listening locally |
Access tokens are opaque and last an hour; refresh tokens last 90 days. The same token works on the REST API as on MCP.