API Reference

The Flowsta Auth API provides OAuth 2.0 + PKCE authentication, Vault sign-in, Sign It signing/verification, and webhook management endpoints.

Base URL

https://auth-api.flowsta.com

Conventions

• Versioning. Newer resources live under the /api/v1/ prefix (/api/v1/sign-it/*, /api/v1/webhooks, /api/v1/apps/verify). The OAuth, sign-in, DID and developer-portal surfaces are unversioned: /oauth/*, /auth/*, /did/*, /developer/*. There is no version header.
• Authentication. Authenticated endpoints take Authorization: Bearer <token>. Which token depends on the endpoint: an OAuth access token for your app (with the scope the endpoint names), or a Flowsta session JWT (a signed-in user, or your developer session at dev.flowsta.com). Public endpoints take no header.
• Error envelope. /oauth/* answers RFC 6749 style, { "error": "...", "error_description": "..." }. Everything else answers { "error": "<code>", "message": "<human-readable>" }, sometimes with extra fields named on the endpoint's page (for example valid_events on a webhook create).
• Rate limits. Limits are per endpoint, not global, and each endpoint's page states its own. A limited request answers 429. For example, creating a webhook is limited to 30 requests per minute; the Sign It verification endpoints share a verification limiter.

OAuth Endpoints

The OAuth 2.0 + PKCE surface - /oauth/authorize, /oauth/token, /oauth/userinfo, and /oauth/revoke - covers the full "Sign in with Flowsta" flow. No client secret is required: PKCE (code_challenge / code_verifier) secures the exchange, so your Client ID is all you need.

Full request/response documentation, scopes, error codes, and rate limits live in the canonical reference:

View the OAuth API Reference →

Token lifetimes at a glance:

Token Type	Lifetime
Authorization Code	10 minutes
Access Token	24 hours
Refresh Token	30 days

Vault Sign-In Endpoints

Device-key sign-in from Flowsta Vault uses a challenge-signature exchange: POST /auth/vault/challenge issues a one-time challenge, and POST /auth/vault/token verifies the device's signature and returns a JWT plus the flowsta_session SSO cookie. Full documentation lives in the OAuth API Reference.

SDK Usage

We recommend using the official SDK instead of calling the API directly:

import { FlowstaAuth } from '@flowsta/auth';

const auth = new FlowstaAuth({
  clientId: 'flowsta_app_abc123',
  redirectUri: 'https://yourapp.com/callback'
});

// Redirect to Flowsta login
auth.login();

// Handle callback (PKCE handled automatically)
const user = await auth.handleCallback();

View SDK Documentation →

Vault IPC Endpoints

Flowsta Vault provides a local IPC API for desktop apps:

• Agent linking (identity attestations)
• Desktop app authentication
• App data backups
• Data signing

View IPC Endpoints →

Sign It Endpoints

Document signing and verification API. Verification endpoints are public - no authentication required.

Endpoint	Method	Auth	Description
/api/v1/sign-it/verify	GET	Public	Look up signatures by file hash
/api/v1/sign-it/verify-file	POST	Public	Upload file for fuzzy perceptual matching
/api/v1/sign-it/verify-fuzzy	POST	Public	Fuzzy lookup with pre-computed bands
/api/v1/sign-it/creator/:id	GET	Public	A signer's public creator profile
/api/v1/sign-it/badge	GET	Public	Verification badge for a file hash
/api/v1/sign-it/content-rights	GET	Public	Machine-readable content rights for a file hash
/api/v1/sign-it/contact	POST	Public	Blind email relay to signer
/api/v1/sign-it/quota	GET	JWT / OAuth (verify scope)	The caller's signing plan and remaining allowance
/api/v1/sign-it/sign	POST	JWT / OAuth (sign scope)	Sign a file hash
/api/v1/sign-it/sign-batch	POST	JWT / OAuth (sign scope)	Sign multiple file hashes
/api/v1/sign-it/my-signatures	GET	JWT / OAuth (verify scope)	Get user's signatures + linked agents
/api/v1/sign-it/revoke	POST	JWT / OAuth (sign scope)	Revoke a signature

View full Sign It API Reference →

Webhook Endpoints

GET /api/v1/webhooks/events (public catalog), and POST / GET / PUT /:id / DELETE /:id on /api/v1/webhooks with a developer token and ?app_id=.

View the Webhooks guide →

Complete Auth Documentation

For detailed documentation including PKCE implementation, framework-specific examples, and security best practices:

View Auth Documentation →

Support

Need help with the API?

• Discord: Join our community
• Support: Find out about Flowsta support options
• GitHub: github.com/WeAreFlowsta