Authentication

Every request carries a bearer token:

Authorization: Bearer <access_token>

The token is an OAuth 2.1 access token (JWT, ES256) issued by the Jolv authorisation server. The API verifies its signature, issuer and audience, and relays it to the database: row-level security then applies the rights of the user who authorised the access. Nothing is shared between users, and the API server holds no secret.

#Interactive authorisation (a person consents)

This is the flow used by Claude connectors, this documentation's playground and any OAuth-capable client (Postman, Insomnia, Bruno) whose return address is on Jolv's trusted list. The documentation's own return address (www.jolv.app/api/oauth/callback) is on that list; a desktop client's local loopback address (http://127.0.0.1:<port>/…) is accepted too.

1. Discovery

   GET https://jolv-mcp.vercel.app/.well-known/oauth-protected-resource

   {
     "resource": "https://jolv-mcp.vercel.app/mcp",
     "authorization_servers": ["https://pfaotkgjdsrgzrqesuup.supabase.co/auth/v1"],
     "scopes_supported": ["openid", "email", "profile"],
     "bearer_methods_supported": ["header"],
     "resource_name": "Jolv"
   }

   The authorisation server publishes its own metadata (authorisation, token and registration endpoints) at /.well-known/oauth-authorization-server under that base URL.

2. Client registration

   The client registers itself with dynamic client registration (RFC 7591) and receives a client_id. No manual approval is needed.

3. Consent in Jolv

   The client opens the authorisation URL (authorisation code flow with PKCE). The user signs in to Jolv, MFA included if enabled on the account, sees which application asks for access, and clicks Authorise or Refuse.

4. Token

   The client exchanges the code at the token endpoint and receives an access token valid for one hour. It sends it on every call. When the token expires, the API answers 401 with a WWW-Authenticate header pointing back to the discovery document.

#Rights and scope

The API does not have its own permission model. The token identifies a Jolv user; the database applies that user's organisation, fund access list, role and status on every row. Consequences:

• A fund or company outside the user's rights is not an error: it is simply absent from the response (empty list, "published": false).
• Suspending the user, or removing a fund from their access, takes effect on the next call.
• A user who can see three funds in the application sees the same three funds through the API.

#Revocation

• Remove the integration on the client side, or
• Revoke the authorisation in the Jolv authorisation server (Supabase Auth → OAuth Apps).

An access token already issued stays valid until it expires (one hour at most), like a web session.

#Unattended integrations

A server that runs without a person (nightly ETL, fund administrator sync) cannot click Authorise. See Server integrations.