Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. By signing up you are subscribing to the APIs.io and API Evangelist
newsletters — you can unsubscribe from any issue. See our
Privacy Policy and Terms.
openapi: 3.2.0
info:
title: Metric Duck Auth Cookies API
description: 'SEC filing data API: equity fundamentals updated daily from SEC EDGAR'
version: 2.0.0
tags:
- name: auth-cookies
paths:
/auth/v2/login:
post:
tags:
- auth-cookies
summary: Login
description: 'Login endpoint using Supabase Auth with HTTP-only cookies.
Sets both access and refresh tokens for secure session management.'
operationId: login_auth_v2_login_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/auth/v2/register:
post:
tags:
- auth-cookies
summary: Register
description: 'Register a new user with Supabase Auth.
Sets HTTP-only cookies if email confirmation is disabled.'
operationId: register_auth_v2_register_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/auth/v2/logout:
post:
tags:
- auth-cookies
summary: Logout
description: Logout endpoint that revokes session, invalidates cache, and clears cookies.
operationId: logout_auth_v2_logout_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/auth/v2/session:
get:
tags:
- auth-cookies
summary: Get Session
description: 'Get current session information using Supabase tokens.
Returns user data if authenticated, or guest info if not.
If the access token is expired/missing but a valid refresh token exists,
automatically refreshes the session (fixes "Remember Me" persistence).'
operationId: get_session_auth_v2_session_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/auth/v2/refresh:
post:
tags:
- auth-cookies
summary: Refresh Session
description: 'Refresh session using Supabase refresh token with proper token rotation.
Invalidates old tokens before setting new ones to prevent race conditions.'
operationId: refresh_session_auth_v2_refresh_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/auth/v2/confirm:
get:
tags:
- auth-cookies
summary: Confirm Email
description: 'Handle email confirmation callback from Supabase.
Exchanges confirmation token for session tokens and sets cookies.'
operationId: confirm_email_auth_v2_confirm_get
parameters:
- name: token_hash
in: query
required: true
schema:
type: string
title: Token Hash
- name: type
in: query
required: true
schema:
type: string
title: Type
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/auth/v2/oauth/callback:
post:
tags:
- auth-cookies
summary: Oauth Callback
description: 'Handle OAuth callback - exchanges Supabase OAuth session for API cookies.
Maintains API as single source of truth for authentication.
Flow:
1. Frontend completes OAuth with Supabase (GitHub/Google)
2. Callback sends tokens to this endpoint
3. API validates tokens and sets session cookies
4. User is authenticated with API session'
operationId: oauth_callback_auth_v2_oauth_callback_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/auth/v2/resend-verification:
post:
tags:
- auth-cookies
summary: Resend Verification
description: 'Resend email verification link.
Rate limited by Supabase (1 per minute per email).'
operationId: resend_verification_auth_v2_resend_verification_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/auth/v2/reset-password:
post:
tags:
- auth-cookies
summary: Reset Password
description: 'Request password reset email.
SECURITY: Always returns generic success message to prevent email enumeration.
This follows OWASP best practices for password reset flows.
Rate limited by our own middleware + Supabase (1 per 60 seconds per email).'
operationId: reset_password_auth_v2_reset_password_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/auth/v2/update-password:
post:
tags:
- auth-cookies
summary: Update Password
description: 'Update password for authenticated user (after recovery flow).
Requires valid session cookie from recovery verification.'
operationId: update_password_auth_v2_update_password_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/auth/v2/mcp-grant:
post:
tags:
- auth-cookies
summary: Create Mcp Grant
description: 'Create a short-lived signed grant for MCP OAuth authorization.
Called by the web app after the user approves the consent card on the MCP authorize
page. Requires a valid session cookie (user must be logged in) and a JSON body
`{"return_to": }` - the grant is BOUND to
that request''s client_id, redirect_uri and code_challenge (#2698).
Returns a signed JWT grant token (60s TTL, single-use) carrying user identity plus the
binding. The MCP worker redeems it, once, for exactly that authorize request.'
operationId: create_mcp_grant_auth_v2_mcp_grant_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/auth/v2/validate-mcp-grant:
post:
tags:
- auth-cookies
summary: Validate Mcp Grant
description: 'Validate, bind-check and consume an MCP grant token.
Called by the MCP worker to exchange a grant for user identity. The grant must carry
the SAME client_id / redirect_uri / code_challenge as the request redeeming it
(`grant_mismatch` otherwise), and its `jti` is consumed once (`grant_reused` on a
second redemption). `detail` is a machine code on every refusal - the worker carries
it into telemetry - never prose.'
operationId: validate_mcp_grant_auth_v2_validate_mcp_grant_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/auth/v2/validate-token:
post:
tags:
- auth-cookies
summary: Validate Bearer Token
description: 'Validate a Supabase JWT and return user identity.
Called by the MCP worker''s resolveExternalToken to validate Supabase JWTs
passed as Bearer tokens by clients using the /mcp/setup page flow.'
operationId: validate_bearer_token_auth_v2_validate_token_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
components:
schemas:
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key