Auth.md
·
This auth.md tells an agent how to authenticate to Verbafy. User OpenID Connect is Clerk. Authorization-server metadata is at https://verbafy.io/.well-known/oauth-authorization-server and https://verbafy.io/.well-known/openid-configuration. The issuer is https://clerk.verbafy.io. Protected-resource metadata is at https://verbafy.io/.well-known/oauth-protected-resource and lists Verbafy API scopes. Unauthorized API calls return WWW-Authenticate: Bearer resource_metadata="https://verbafy.io/.well-known/oauth-protected-resource".
Verbafy does not issue OAuth access tokens of its own. Clerk OIDC tokens prove a Registered User for browser REST. They do not encode transcripts:read or other API capability scopes. Remote MCP uses a Registered User API Key (sk-…). Current keys are full-access for that Registered User. Named scopes in OpenAPI and RFC 9728 scopes_supported are the least-privilege grants agents should request; they are not yet enforced on keys. API Keys and Guest sessions are Verbafy application credentials, not Clerk OAuth grants. identity_assertion (id-jag), verified_email assertions, and anonymous assertion tokens are not supported. Do not POST /agent/auth.
Discover
Start at https://verbafy.io/developers, https://verbafy.io/llms.txt, https://verbafy.io/docs, and https://verbafy.io/openapi.json. Remote MCP is at https://verbafy.io/api/v1/mcp (Streamable HTTP). MCP discovery is at https://verbafy.io/.well-known/mcp.json. Human support is support@verbafy.io.
On 401, read WWW-Authenticate: Bearer resource_metadata="https://verbafy.io/.well-known/oauth-protected-resource". Fetch that Protected Resource Metadata. Read resource, resource_name, authorization_servers, scopes_supported, and bearer_methods_supported.
Then fetch Authorization Server metadata at https://clerk.verbafy.io/.well-known/oauth-authorization-server. Verbafy also publishes a copy plus agent_auth at https://verbafy.io/.well-known/oauth-authorization-server and OpenID discovery at https://verbafy.io/.well-known/openid-configuration. issuer is https://clerk.verbafy.io in both. agent_auth.skill is this file. agent_auth.register_uri is https://verbafy.io/app/settings/api-keys. There is no RFC 7591 dynamic client registration.
Pick a method
Pick one credential:
- Registered User REST: Clerk session JWT on
Authorization: Bearer. Clerk issues that token after website login. Verbafy does not show a JWT in Settings. - Guest REST:
verbafy_guest_sessionHttpOnly cookie. Guests cannot call MCP. - Registered User MCP: API Key
sk-…onAuthorization: Bearer. Use this for scripts and agents.
identity_assertion (including id-jag) is not supported. anonymous guest access uses the cookie, not an assertion token.
Register
Humans create a Clerk account or a Guest session in the product. Agents that need a long-lived MCP credential must use a Registered User. Open https://verbafy.io/app/settings/api-keys while signed in, or POST https://verbafy.io/api/v1/me/api-keys with a Clerk Bearer JWT, and create a named key. That is the complete registered_user_api_key method in agent_auth.
Claim
Guest data is claimed onto a Clerk user at /auth/complete. That path is for browsers after sign-in. Agents should not POST a claim. An API Key is claimed when it is created: the secret is shown once.
Use the credential
Same-origin REST: https://verbafy.io/api/v1. Send the Clerk JWT as Authorization: Bearer, or send the guest cookie. MCP: Authorization: Bearer sk-… only. Read OpenAPI for request bodies. Do not send storage credentials. Do not call unpublished API origins.
Errors
JSON errors use { message, code, hint, issues }. 401 means the credential is missing, expired, or revoked. Read WWW-Authenticate and the protected-resource metadata. 403 means the user cannot use MCP (guests). 402 means the plan does not allow the operation. 429 on guest-session create includes Retry-After.
Revocation
Revoke an API Key with DELETE /api/v1/me/api-keys/{id} or Settings → API keys. After revoke, the secret returns 401. Sign out of Clerk to end a registered browser session. Revoke the current Guest session with DELETE /api/v1/auth/guest-sessions/current; the response also clears the cookie. Clerk token revocation is https://clerk.verbafy.io/oauth/token/revoke.