---
title: "Auth.md"
description: "How agents obtain Clerk JWTs, guest cookies, and Registered User API Keys for Verbafy."
canonical: "https://verbafy.io/auth"
last-updated: "2026-09-23"
---

# 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. Guest sessions expire; there is no public revoke URL for the cookie. Clerk token revocation is `https://clerk.verbafy.io/oauth/token/revoke`.

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://verbafy.io/#organization",
      "name": "Verbafy",
      "url": "https://verbafy.io",
      "inLanguage": "en",
      "knowsAbout": [
        "YouTube transcription",
        "Spotify episode transcription",
        "Meeting recording transcription",
        "Speaker diarization",
        "Transcript export"
      ],
      "hasOfferCatalog": {
        "@id": "https://verbafy.io/pricing#offers"
      },
      "contactPoint": {
        "@type": "ContactPoint",
        "contactType": "customer support",
        "email": "support@verbafy.io",
        "url": "https://verbafy.io/contact"
      }
    },
    {
      "@type": "TechArticle",
      "@id": "https://verbafy.io/auth#page",
      "name": "Verbafy agent authentication",
      "description": "How agents obtain Clerk JWTs, guest cookies, and Registered User API Keys for Verbafy.",
      "url": "https://verbafy.io/auth",
      "inLanguage": "en",
      "isPartOf": {
        "@id": "https://verbafy.io/#website"
      },
      "publisher": {
        "@id": "https://verbafy.io/#organization"
      }
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://verbafy.io"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Verbafy agent authentication",
          "item": "https://verbafy.io/auth"
        }
      ]
    }
  ]
}
```