API Reference

ModernSaaS API

Build powerful integrations with our REST API. Complete documentation, code examples, and authentication guides.

Authentication Endpoints Rate Limits Back to Docs

Authentication

Secure your API requests

All API requests must include an authentication header. We support API key authentication via Bearer tokens.

API Key Authentication

Include your API key in the Authorization header of every request:

Authorization Header Required
Authorization: Bearer YOUR_API_KEY

Getting Your API Key

  1. 1 Log in to your ModernSaaS dashboard
  2. 2 Navigate to Settings → API Keys
  3. 3 Click "Generate New Key"
  4. 4 Copy and store your key securely (it won't be shown again)

Quick Start

Copy-paste ready code examples in your favorite language

cURL 
                    curl -X GET "https://api.modernsaas.dev/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
JavaScript 
                    const response = await fetch('https://api.modernsaas.dev/v1/users', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);
Python 
                    import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
}

response = requests.get('https://api.modernsaas.dev/v1/users', headers=headers)
data = response.json()
print(data)
Ruby 
                    require 'net/http'
require 'json'

uri = URI('https://api.modernsaas.dev/v1/users')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer YOUR_API_KEY'
req['Content-Type'] = 'application/json'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(req)
end

puts JSON.parse(res.body)

Endpoints

REST API reference for user management

https://api.modernsaas.dev
GET /v1/users Bearer Token

List all users in your organization

Parameters

Name Type Required Description
limit integer Optional Number of results to return (max 100)
cursor string Optional Pagination cursor for next page

Response

                      {
  "data": [
    {
      "id": "usr_123456789",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "admin",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6MTIzfQ=="
  }
}
POST /v1/users Bearer Token

Create a new user in your organization

Parameters

Name Type Required Description
email string Required User email address
name string Required User full name
role string Optional User role (admin, member, guest)

Response

                      {
  "id": "usr_987654321",
  "email": "newuser@example.com",
  "name": "Jane Smith",
  "role": "member",
  "created_at": "2024-06-20T14:45:00Z",
  "status": "active"
}
GET /v1/users/{id} Bearer Token

Retrieve a specific user by ID

Parameters

Name Type Required Description
id string Required User ID

Response

                      {
  "id": "usr_123456789",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "admin",
  "created_at": "2024-01-15T10:30:00Z",
  "last_login": "2024-06-20T09:00:00Z",
  "preferences": {
    "timezone": "America/New_York",
    "notifications": true
  }
}
PUT /v1/users/{id} Bearer Token

Update an existing user

Parameters

Name Type Required Description
id string Required User ID
name string Optional User full name
role string Optional User role

Response

                      {
  "id": "usr_123456789",
  "email": "user@example.com",
  "name": "John Doe Jr.",
  "role": "member",
  "updated_at": "2024-06-20T15:30:00Z"
}
DELETE /v1/users/{id} Bearer Token

Delete a user from your organization

Parameters

Name Type Required Description
id string Required User ID

Response

                      {
  "id": "usr_123456789",
  "deleted": true,
  "deleted_at": "2024-06-20T16:00:00Z"
}

Rate Limiting

Understand our rate limits and best practices

To ensure fair usage and platform stability, API requests are rate-limited based on your plan. Rate limits are enforced per API key.

Free

100

requests/minute

Burst: 10

Starter

1,000

requests/minute

Burst: 100

Pro

10,000

requests/minute

Burst: 1,000

Enterprise

Unlimited

requests/minute

Burst: 10,000

Rate Limit Headers

Every API response includes headers indicating your current rate limit status:

X-RateLimit-Limit Maximum requests allowed per window
X-RateLimit-Remaining Requests remaining in current window
X-RateLimit-Reset Unix timestamp when the window resets

Error Handling

HTTP status codes and error responses

Code Name Description
200 OK Request succeeded
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
403 Forbidden Insufficient permissions
404 Not Found Resource does not exist
429 Rate Limited Too many requests
500 Server Error Internal server error

Error Response Format

Example Error Response (400 Bad Request) 
{
  "error": {
    "code": "invalid_request",
    "message": "The request is missing required parameters",
    "details": [
      {
        "field": "email",
        "message": "Email is required"
      }
    ],
    "request_id": "req_abc123xyz"
  }
}

Webhooks

Receive real-time event notifications

Webhooks allow you to receive real-time HTTP notifications when events occur in your ModernSaaS account. Instead of polling our API, webhooks push data to your endpoint as events happen.

Supported Events

  • user.created - New user created
  • user.updated - User information updated
  • user.deleted - User deleted
  • workspace.created - New workspace created
  • billing.payment_succeeded - Payment processed

Security

  • Webhook signatures for verification
  • HTTPS endpoints required
  • Automatic retries for failed deliveries
  • IP allowlisting available
  • Payload encryption support
Webhook Payload Example 
{
  "id": "evt_1234567890",
  "object": "event",
  "type": "user.created",
  "created": 1718901234,
  "data": {
    "id": "usr_987654321",
    "email": "user@example.com",
    "name": "John Doe",
    "created_at": "2024-06-20T14:45:00Z"
  }
}

Build Your Own Integration

Can't find what you need? Our comprehensive REST and GraphQL APIs let you build custom integrations.

Comprehensive REST API
GraphQL endpoint
Webhook support
SDKs for popular languages
Detailed documentation
Developer community
View API Docs Contact Developer Support