Authentication

Trove uses Clerk for authentication. All API requests must include a valid token.

Token Types

Trove accepts two types of tokens, depending on how you integrate.

Clerk Session JWTs

Use for: Direct API calls from your app.

Session JWTs (typ: JWT) are issued by Clerk’s frontend SDKs when a user signs in. They are short-lived (minutes) and automatically refreshed by the Clerk SDK.

Obtain them via Clerk’s SDK integration in your app, then send them with each API request.

Clerk OAuth Access Tokens

Use for: MCP clients (Claude Desktop, Cursor).

OAuth access tokens (typ: at+jwt, per RFC 9068) are obtained automatically by MCP clients through the OAuth 2.1 flow with PKCE (Proof Key for Code Exchange).

Supported scopes: profile, email, offline_access.

You do not need to configure this manually. MCP clients handle the token exchange after you authenticate in the browser.

Sending Tokens

Include your token using one of these methods:

Method	Format	Recommended for
Header	Authorization: Bearer <token>	API calls, MCP clients
Cookie	__session=<token>	Browser-based apps

The Authorization header is the recommended approach for all non-browser integrations.

OAuth Discovery

MCP clients discover Trove’s auth configuration automatically using standard metadata endpoints.

Protected Resource Metadata (RFC 9728)

curl https://api.ontrove.sh/.well-known/oauth-protected-resource

{
  "resource": "https://api.ontrove.sh/mcp",
  "authorization_servers": ["https://your-instance.clerk.accounts.dev"],
  "scopes_supported": ["profile", "email", "offline_access"],
  "bearer_methods_supported": ["header"]
}

Authorization Server Metadata (RFC 8414)

curl https://api.ontrove.sh/.well-known/oauth-authorization-server

Returns Clerk’s OAuth metadata including the authorization endpoint, token endpoint, supported grant types, and PKCE configuration.

Error Handling

Unauthenticated requests return 401 with a WWW-Authenticate header:

WWW-Authenticate: Bearer resource_metadata="https://api.ontrove.sh/.well-known/oauth-protected-resource"

MCP clients use this header to discover the auth server and initiate the OAuth flow automatically.

Common error responses:

Status	Meaning
401 Unauthorized	Missing or invalid token

Token Lifetime

Token type	Lifetime	Renewal
Session JWT	Short-lived (minutes)	Automatically refreshed by Clerk SDK
OAuth access token	Longer-lived	Refresh token via offline_access scope

Getting Tokens in Code

For server-side apps using Clerk’s SDK:

import { createClerkClient } from '@clerk/backend';

const clerk = createClerkClient({ secretKey: 'sk_...' });
// For server-to-server: use Clerk API keys
// For user-facing apps: use Clerk's frontend SDKs

For user-facing apps, use Clerk’s frontend SDKs to handle sign-in and token management. The SDK provides the session JWT automatically with each request.

Example: React with Clerk

import { useAuth } from '@clerk/clerk-react';

function useTroveSearch() {
  const { getToken } = useAuth();

  return async function search(query: string) {
    const token = await getToken();
    const res = await fetch('https://api.ontrove.sh/graphql', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        query: 'query Search($q: String!) { search(query: $q) { results { document { title } snippet } } }',
        variables: { q: query },
      }),
    });
    return res.json();
  };
}

Next Steps

• Quickstart: Connect Your AI Assistant: MCP setup with automatic OAuth
• Quickstart: Your First API Call: Using tokens with the GraphQL API