Verbafy

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_session HttpOnly cookie. Guests cannot call MCP.
  • Registered User MCP: API Key sk-… on Authorization: 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.