API Reference

The Flowsta Auth API provides OAuth 2.0 + PKCE authentication endpoints.

Base URL

https://auth-api.flowsta.com

Authentication Methods

Endpoint	Authentication
/oauth/authorize	None (public)
/oauth/token	PKCE (client_id + code_verifier)
/oauth/userinfo	Bearer token
/oauth/revoke	X-Client-Id header

No Client Secret Required

Flowsta uses PKCE, which provides security without client secrets. Your Client ID is all you need!

OAuth Endpoints

Authorization Endpoint

GET /oauth/authorize

Start the OAuth flow by redirecting users here.

Parameters:

Parameter	Required	Description
response_type	✅	Must be code
client_id	✅	Your Client ID
redirect_uri	✅	Callback URL
scope	✅	Space-separated scopes
state	⚠️	CSRF protection (recommended)
code_challenge	✅	PKCE challenge
code_challenge_method	✅	Must be S256

Example:

https://auth-api.flowsta.com/oauth/authorize?
  response_type=code&
  client_id=flowsta_app_abc123&
  redirect_uri=https://yourapp.com/callback&
  scope=profile%20email&
  state=random_state&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256

Token Endpoint

POST /oauth/token
Content-Type: application/json

Exchange authorization code for tokens.

Request Body:

{
  "grant_type": "authorization_code",
  "code": "authorization_code_here",
  "redirect_uri": "https://yourapp.com/callback",
  "client_id": "flowsta_app_abc123",
  "code_verifier": "your_pkce_code_verifier"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_token_here",
  "scope": "profile email"
}

User Info Endpoint

GET /oauth/userinfo
Authorization: Bearer <access_token>

Get authenticated user's profile.

Response:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John Doe",
  "preferred_username": "johndoe",
  "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "agent_pub_key": "uhCAk7JpEWfkiV...",
  "profile_picture": "https://...",
  "has_custom_picture": false,
  "email": "john@example.com",
  "email_verified": true,
  "scope": "profile email"
}

Token Revocation

POST /oauth/revoke
Content-Type: application/json
X-Client-Id: flowsta_app_abc123

Revoke a refresh token.

Request Body:

{
  "token": "refresh_token_here",
  "token_type_hint": "refresh_token"
}

Scopes

Scope	Data Included
profile	sub, name, preferred_username, did, agent_pub_key, profile_picture
email	email, email_verified (requires user permission)

Error Responses

400 Bad Request:

{
  "error": "invalid_request",
  "error_description": "Missing required parameter: code_verifier"
}

401 Unauthorized:

{
  "error": "invalid_token",
  "error_description": "Access token is invalid or expired"
}

Token Lifetimes

Token Type	Lifetime
Authorization Code	10 minutes
Access Token	1 hour
Refresh Token	30 days (sliding)

Rate Limiting

Endpoint	Limit
/oauth/authorize	100/min per IP
/oauth/token	50/min per client
/oauth/userinfo	500/min per token
/oauth/revoke	50/min per client

Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699564800

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 →

Complete OAuth Documentation

For detailed OAuth documentation including:

• PKCE implementation guide
• Framework-specific examples (React, Vue, Qwik)
• Security best practices
• Session management

View OAuth Documentation →

Support

Need help with the API?

• 📚 SDK Documentation
• 🐛 Report an Issue
• 💬 Discord Community
• 📧 Email Support