Skip to main content
Planned feature: The API endpoints described in this section represent the intended REST API design for OrgStack. These endpoints are not yet implemented in the current codebase. This documentation serves as a specification for the planned API architecture.

​
Overview

The planned OrgStack API will be a RESTful API that enables you to programmatically manage organizations, users, roles, and permissions in a multi-tenant environment. The API will follow standard REST conventions and return JSON-encoded responses.
All API requests will require authentication using JWT bearer tokens. Learn more in the Authentication specification.

​
Base URL

All API endpoints are relative to the base URL: 
http://localhost:8080/api
For example, to access the login endpoint, you would make a request to: 
http://localhost:8080/api/auth/login

​
API versioning

The OrgStack API currently uses URL-based versioning. The base URL includes the API version path segment. Future versions will be introduced as needed to maintain backward compatibility.

​
Request format

All requests that send data in the request body must use JSON format and include the appropriate Content-Type header: 
Content-Type: application/json

​
Example request

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "securepassword"
  }'

​
Response format

All API responses are returned in JSON format. Successful responses include the requested data, while error responses include details about what went wrong.

​
Success response example

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Acme Corporation",
  "status": "active"
}

​
Error response example

{
  "error": "Unauthorized",
  "message": "Invalid or expired token",
  "timestamp": "2026-03-01T10:30:00Z"
}

​
HTTP status codes

The OrgStack API uses standard HTTP status codes to indicate the success or failure of requests:
Status CodeDescription
200OK - Request succeeded
201Created - Resource created successfully
400Bad Request - Invalid request parameters or body
401Unauthorized - Missing or invalid authentication token
403Forbidden - Authenticated but lacking permission
404Not Found - Resource does not exist
500Internal Server Error - Server encountered an error
When you receive a 4xx error, check the response body for detailed error messages to help troubleshoot the issue.

​
Common patterns

​
Pagination

List endpoints support pagination using page and size query parameters: 
GET /api/organizations?page=0&size=20
Paginated responses include metadata about the total number of items and pages: 
{
  "content": [...],
  "page": 0,
  "size": 20,
  "totalElements": 100,
  "totalPages": 5
}

​
Filtering and sorting

Many endpoints support filtering and sorting through query parameters: 
GET /api/users?status=active&sort=createdAt,desc

​
Multi-tenancy

OrgStack is built for multi-tenant environments. Your authentication token determines which organization context you’re operating in. Some endpoints may require you to specify an organization ID explicitly.
Always ensure you’re operating in the correct organization context to avoid accessing or modifying data for the wrong tenant.

​
Rate limiting

To ensure fair usage and API stability, rate limiting may be applied to API requests. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

​
Getting help

If you encounter issues or have questions about the API:
  • Check the specific endpoint documentation for detailed information
  • Review the Authentication guide for token-related issues
  • Inspect error response messages for troubleshooting guidance

​
Next steps

1

Authenticate

Learn how to obtain and use JWT tokens in the Authentication guide.
2

Explore endpoints

Browse the available API endpoints to understand what operations you can perform.
3

Build your integration

Start making API calls to integrate OrgStack into your application.

Build docs developers (and LLMs) love

Get started for freeTalk to us