Site Blocklist API

Complete API reference for Site Blocklist Management endpoints.

Base URL

Production: https://auth-api.flowsta.com
Staging:    https://auth-api-staging.flowsta.com

Authentication

All blocklist endpoints require client authentication via headers:

http

X-Client-Id: your_client_id
X-Client-Secret: your_client_secret  # Only for write operations

Read operations (GET): Require X-Client-Id only
Write operations (POST/DELETE): Require both X-Client-Id and X-Client-Secret

Endpoints

POST /sites/block-user

Block a user from accessing your site.

Authentication: X-Client-Id + X-Client-Secret required

Request:

http

POST /sites/block-user
Content-Type: application/json
X-Client-Id: flowsta_app_abc123
X-Client-Secret: your_secret_here

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "reason": "Violation of community guidelines"
}

Parameters:

Field	Type	Required	Description
`userId`	string (UUID)	Yes	User's unique identifier
`reason`	string	No	Reason for blocking (max 500 chars)

Response: 200 OK

json

{
  "success": true,
  "message": "User blocked successfully",
  "blockedUser": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "blockedAt": "2025-11-05T10:30:00.000Z",
    "reason": "Violation of community guidelines"
  }
}

Error Responses:

json

// 404 Not Found - User doesn't exist
{
  "error": "User not found",
  "message": "The specified user does not exist"
}

// 409 Conflict - User already blocked
{
  "error": "User already blocked",
  "message": "This user is already blocked from your site"
}

// 401 Unauthorized - Missing or invalid credentials
{
  "error": "Invalid client secret",
  "message": "The provided client secret is incorrect"
}

DELETE /sites/unblock-user

Remove a user from your site's blocklist.

Authentication: X-Client-Id + X-Client-Secret required

Request:

http

DELETE /sites/unblock-user
Content-Type: application/json
X-Client-Id: flowsta_app_abc123
X-Client-Secret: your_secret_here

{
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

Parameters:

Field	Type	Required	Description
`userId`	string (UUID)	Yes	User's unique identifier

Response: 200 OK

json

{
  "success": true,
  "message": "User unblocked successfully",
  "unblockedUser": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "unblockedAt": "2025-11-05T11:00:00.000Z"
  }
}

Error Responses:

json

// 404 Not Found - User not in blocklist
{
  "error": "User not blocked",
  "message": "This user is not in your blocklist"
}

GET /sites/blocked-users

Get paginated list of all blocked users for your site.

Authentication: X-Client-Id required (read operation)

Request:

http

GET /sites/blocked-users?page=1&limit=50
X-Client-Id: flowsta_app_abc123

Query Parameters:

Parameter	Type	Required	Default	Description
`page`	number	No	1	Page number (1-indexed)
`limit`	number	No	50	Results per page (max: 100)

Response: 200 OK

json

{
  "success": true,
  "blockedUsers": [
    {
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "displayName": "John Doe",
      "email": "a1b2c3d4e5f6...",
      "did": "did:flowsta:uhCAkSomeAgentPubKeyHash",
      "blockedAt": "2025-11-05T10:30:00.000Z",
      "reason": "Violation of community guidelines"
    },
    {
      "userId": "660e8400-e29b-41d4-a716-446655440111",
      "displayName": "Jane Smith",
      "email": "d4e5f6g7h8i9...",
      "did": "did:flowsta:uhCAkAnotherAgentPubKeyHash",
      "blockedAt": "2025-11-04T15:20:00.000Z",
      "reason": "Spam posting"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "totalBlocked": 127,
    "totalPages": 3,
    "hasMore": true
  }
}

Fields:

Field	Type	Description
`userId`	string	User's unique identifier
`displayName`	string \| null	User's display name (if set)
`email`	string	Hashed email (for identification)
`did`	string \| null	Decentralized identifier
`blockedAt`	string (ISO 8601)	When user was blocked
`reason`	string \| null	Reason for blocking

GET /sites/check-user-status/:userId

Check if a specific user is blocked from your site.

Authentication: X-Client-Id required (read operation)

Request:

http

GET /sites/check-user-status/550e8400-e29b-41d4-a716-446655440000
X-Client-Id: flowsta_app_abc123

URL Parameters:

Parameter	Type	Required	Description
`userId`	string (UUID)	Yes	User's unique identifier

Response: 200 OK (User is blocked)

json

{
  "success": true,
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "isBlocked": true,
  "blockDetails": {
    "blockedAt": "2025-11-05T10:30:00.000Z",
    "reason": "Violation of community guidelines"
  }
}

Response: 200 OK (User is NOT blocked)

json

{
  "success": true,
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "isBlocked": false,
  "blockDetails": null
}

Error Responses:

json

// 400 Bad Request - Invalid UUID format
{
  "error": "Invalid user ID format",
  "message": "User ID must be a valid UUID"
}

GET /sites/stats

Get statistics about your site's blocklist and users.

Authentication: X-Client-Id required (read operation)

Request:

http

GET /sites/stats
X-Client-Id: flowsta_app_abc123

Response: 200 OK

json

{
  "success": true,
  "stats": {
    "totalBlockedUsers": 127,
    "blocksLast30Days": 15,
    "totalActiveUsers": 5432,
    "siteName": "My Awesome App",
    "siteId": "770e8400-e29b-41d4-a716-446655440222"
  }
}

Fields:

Field	Type	Description
`totalBlockedUsers`	number	Total users currently blocked
`blocksLast30Days`	number	New blocks in last 30 days
`totalActiveUsers`	number	Total active users (not blocked)
`siteName`	string	Your site/app name
`siteId`	string	Your site/app UUID

Rate Limits

Rate limits are applied per clientId:

Endpoint	Rate Limit	Window
`POST /sites/block-user`	100 requests	per minute
`DELETE /sites/unblock-user`	100 requests	per minute
`GET /sites/blocked-users`	300 requests	per minute
`GET /sites/check-user-status/:userId`	1000 requests	per minute
`GET /sites/stats`	60 requests	per minute

When rate limit is exceeded:

json

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 60
}

Error Codes

Status Code	Meaning
`200`	Success
`400`	Bad Request - Invalid input
`401`	Unauthorized - Missing or invalid clientId
`403`	Forbidden - Invalid clientSecret or insufficient permissions
`404`	Not Found - Resource doesn't exist
`409`	Conflict - Resource already exists (e.g., user already blocked)
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Automatic Enforcement

Blocklist checks are automatically enforced during token verification.

When you verify a token with a siteId, Flowsta checks the blocklist:

http

POST /auth/verify-token
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "siteId": "770e8400-e29b-41d4-a716-446655440222"
}

Response (user is blocked):

json

{
  "error": "User is blocked from this site",
  "valid": false
}

Response (user is NOT blocked):

json

{
  "valid": true,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "agentPubKey": "uhCAk..."
  }
}

Code Examples

JavaScript / Node.js

Using @flowsta/auth-client SDK (recommended):

javascript

import { FlowstaClient } from '@flowsta/auth-client';

const flowsta = new FlowstaClient({
  clientId: process.env.FLOWSTA_CLIENT_ID,
  clientSecret: process.env.FLOWSTA_CLIENT_SECRET
});

// Block a user
await flowsta.blockUser({
  userId: '550e8400-e29b-41d4-a716-446655440000',
  reason: 'Violation of ToS'
});

// Get blocked users
const { blockedUsers, pagination } = await flowsta.getBlockedUsers(1, 50);

cURL

bash

# Block a user
curl -X POST https://auth-api.flowsta.com/sites/block-user \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: flowsta_app_abc123" \
  -H "X-Client-Secret: your_secret_here" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "Spam posting"
  }'

# Get blocked users
curl https://auth-api.flowsta.com/sites/blocked-users?page=1&limit=50 \
  -H "X-Client-Id: flowsta_app_abc123"

# Check user status
curl https://auth-api.flowsta.com/sites/check-user-status/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Client-Id: flowsta_app_abc123"

Python

python

import requests

BASE_URL = "https://auth-api.flowsta.com"
CLIENT_ID = "flowsta_app_abc123"
CLIENT_SECRET = "your_secret_here"

# Block a user
response = requests.post(
    f"{BASE_URL}/sites/block-user",
    headers={
        "Content-Type": "application/json",
        "X-Client-Id": CLIENT_ID,
        "X-Client-Secret": CLIENT_SECRET
    },
    json={
        "userId": "550e8400-e29b-41d4-a716-446655440000",
        "reason": "Violation of community guidelines"
    }
)

result = response.json()
print(f"Blocked: {result['success']}")

Security Considerations

Never Expose Client Secret

⚠️ Critical: Your client secret must NEVER be exposed in:

Frontend JavaScript code
Mobile app binaries
Public repositories
Client-side storage

Always use server-side code for write operations (block/unblock).

Server-Side Example

javascript

// ✅ GOOD - Backend route
app.post('/api/admin/block-user', requireAdmin, async (req, res) => {
  const { userId, reason } = req.body;
  
  // Server-side call with secret
  await flowsta.blockUser({ userId, reason });
  
  res.json({ success: true });
});

javascript

// ❌ BAD - Frontend code
// NEVER do this - exposes secret!
const flowsta = new FlowstaClient({
  clientSecret: 'flowsta_secret_abc123' // ❌ EXPOSED!
});

Next Steps

Check SDK Documentation for client library usage
Review Security Best Practices for security guidelines
See OAuth Integration for authentication flows

Support

Need help?

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

Site Blocklist API ​

Base URL ​

Authentication ​

Endpoints ​

POST /sites/block-user ​

DELETE /sites/unblock-user ​

GET /sites/blocked-users ​

GET /sites/check-user-status/:userId ​

GET /sites/stats ​

Rate Limits ​

Error Codes ​

Automatic Enforcement ​

Code Examples ​

JavaScript / Node.js ​

cURL ​

Python ​

Security Considerations ​

Never Expose Client Secret ​

Server-Side Example ​

Next Steps ​

Support ​

Site Blocklist API

Base URL

Authentication

Endpoints

POST /sites/block-user

DELETE /sites/unblock-user

GET /sites/blocked-users

GET /sites/check-user-status/:userId

GET /sites/stats

Rate Limits

Error Codes

Automatic Enforcement

Code Examples

JavaScript / Node.js

cURL

Python

Security Considerations

Never Expose Client Secret

Server-Side Example

Next Steps

Support