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	Client ID in request body (client_id)

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=openid%20display_name%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": 86400,
  "refresh_token": "refresh_token_here",
  "scope": "openid display_name 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": "openid display_name email"
}

Token Revocation

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

Revoke a refresh token.

Request Body:

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

Scopes

Scope	Data Included
openid	sub (user UUID) - auto-included
display_name	name
username	preferred_username
email	email, email_verified (requires user permission)
profile_picture	profile_picture, has_custom_picture
did	did (W3C Decentralized Identifier)
public_key	agent_pub_key (Holochain agent public key)
holochain	agent_pub_key, did (Holochain identity access)

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	24 hours
Refresh Token	30 days

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 →

Vault IPC Endpoints

Flowsta Vault provides a local IPC API for desktop apps:

• Agent linking (identity attestations)
• Desktop app authentication
• Source chain backups
• Data signing

View IPC Endpoints →

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