Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

feat(auth): resolve OAuth access tokens via introspection (#3234)

firecrawl-spring[bot]031ee00b7242
diff --git a/apps/api/src/config.ts b/apps/api/src/config.ts
index 907b57c9b..ffeb56d2d 100644
--- a/apps/api/src/config.ts
+++ b/apps/api/src/config.ts
@@ -66,6 +66,10 @@ const configSchema = z.object({
SEARCH_FEEDBACK_MAX_AGE_SEC: z.coerce.number().int().positive().default(120),
SEARCH_FEEDBACK_DAILY_CAP_CREDITS: z.coerce.number().int().nonnegative().default(100),
+ // OAuth token introspection
+ OAUTH_INTROSPECT_URL: z.string().optional(),
+ OAUTH_INTROSPECT_SECRET: z.string().optional(),
+
// Database & Storage
POSTGRES_HOST: z.string().default("localhost"),
POSTGRES_PORT: z.string().default("5432"),
diff --git a/apps/api/src/controllers/auth.ts b/apps/api/src/controllers/auth.ts
index da0ee62f1..8c3b457bb 100644
--- a/apps/api/src/controllers/auth.ts
+++ b/apps/api/src/controllers/auth.ts
@@ -1,3 +1,4 @@
+import * as crypto from "crypto";
import { RateLimiterRedis } from "rate-limiter-flexible";
import { validate } from "uuid";
import { config } from "../config";
@@ -140,6 +141,95 @@ const mockACUC: () => AuthCreditUsageChunk = () => ({
is_extract: false,
});
+/**
+ * Introspection response from the OAuth token endpoint.
+ */
+interface OAuthIntrospectionResponse {
+ active: boolean;
+ api_key: string;
+ scope: string;
+ client_id: string;
+ team_id: string;
+ exp: number;
+}
+
+/**
+ * Resolve an OAuth access token (fco_…) to the underlying API key via
+ * the introspection endpoint. Results are cached in Redis for the
+ * remaining token TTL (up to 5 minutes).
+ */
+async function resolveOAuthToken(
+ token: string,
+): Promise<OAuthIntrospectionResponse | null> {
+ const introspectUrl = config.OAUTH_INTROSPECT_URL;
+ const introspectSecret = config.OAUTH_INTROSPECT_SECRET;
+
+ if (!introspectUrl || !introspectSecret) {
+ logger.warn(
+ "OAuth introspection not configured (OAUTH_INTROSPECT_URL / OAUTH_INTROSPECT_SECRET)",
+ );
+ return null;
+ }
+
+ // Check Redis cache first (hash the token to avoid leaking material in key names)
+ const tokenHash = crypto
+ .createHash("sha256")
+ .update(token)
+ .digest("hex")
+ .substring(0, 32);
+ const cacheKey = `oauth_token:${tokenHash}`;
+ const cached = await getValue(cacheKey);
+ if (cached !== null) {
+ try {
+ const parsed = JSON.parse(cached);
+ if (!parsed.active) return null;
+ return parsed;
+ } catch {
+ // Corrupt cache entry β€” treat as a miss
+ }
+ }
+
+ try {
+ const response = await fetch(introspectUrl, {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/json",
+ Authorization: `Bearer ${introspectSecret}`,
+ },
+ body: JSON.stringify({ token }),
+ });
+
+ if (!response.ok) {
+ logger.error("OAuth introspection request failed", {
+ status: response.status,
+ });
+ return null;
+ }
+
+ const data = (await response.json()) as OAuthIntrospectionResponse;
+
+ // Cache the result β€” use remaining TTL (max 5 minutes) or 60s for inactive
+ if (data.active) {
+ const remainingSeconds = Math.max(
+ 0,
+ data.exp - Math.floor(Date.now() / 1000),
+ );
+ const cacheTtl = Math.min(remainingSeconds, 300); // Cap at 5 minutes
+ if (cacheTtl > 0) {
+ await setValue(cacheKey, JSON.stringify(data), cacheTtl);
+ }
+ } else {
+ // Cache negative results briefly to avoid hammering introspection
+ await setValue(cacheKey, JSON.stringify({ active: false }), 60);
+ }
+
+ return data.active ? data : null;
+ } catch (error) {
+ logger.error("OAuth introspection error", { error });
+ return null;
+ }
+}
+
/** @public used by auto_charge.ts (disabled, Autumn handles auto-recharge) */
export async function getACUC(
api_key: string,
@@ -479,6 +569,40 @@ async function supaAuthenticateUser(
rateLimiter = getRateLimiter(RateLimiterMode.Preview, token);
}
teamId = `preview_${iptoken}`;
+ } else if (token.startsWith("fco_")) {
+ // OAuth access token β€” resolve via introspection endpoint
+ const introspection = await resolveOAuthToken(token);
+ if (!introspection) {
+ return {
+ success: false,
+ error: "Unauthorized: Invalid or expired OAuth token",
+ status: 401,
+ };
+ }
+
+ // Use the resolved fc- API key to get the normal ACUC chunk
+ const resolvedApi = parseApi(introspection.api_key);
+ chunk = await getACUC(resolvedApi, false, true, RateLimiterMode.Scrape);
+ chunk = await ensureChunkOrgId(resolvedApi, chunk);
+
+ if (chunk === null) {
+ return {
+ success: false,
+ error: "Unauthorized: Invalid token",
+ status: 401,
+ };
+ }
+
+ teamId = chunk.team_id;
+ priceId = chunk.price_id;
+
+ subscriptionData = {
+ team_id: teamId,
+ };
+ rateLimiter = getRateLimiter(
+ mode ?? RateLimiterMode.Crawl,
+ chunk.rate_limits,
+ );
} else {
normalizedApi = parseApi(token);
if (!normalizedApiIsUuid(normalizedApi)) {