API Overview

Taruvi provides a comprehensive REST API built with Django REST Framework, featuring JWT authentication, comprehensive documentation, and tenant-aware endpoints.

Base URLs

The API is accessible at different endpoints depending on the context:

# Platform API (shared resources)
https://api.yourdomain.com/api/

# Tenant-specific API
https://tenant.yourdomain.com/api/

# Development
http://localhost:8000/api/                    # Platform API
http://tenant.127.0.0.1.nip.io:8000/api/     # Tenant API

API Documentation

Interactive Documentation

Swagger UI: /api/docs/ - Interactive API explorer
ReDoc: /api/redoc/ - Clean, responsive documentation
OpenAPI Schema: /api/schema/ - Machine-readable API specification

Example URLs

# Production
https://api.yourdomain.com/api/docs/
https://tenant.yourdomain.com/api/docs/

# Development
http://localhost:8000/api/docs/
http://tenant.127.0.0.1.nip.io:8000/api/docs/

Authentication

Taruvi uses JWT (JSON Web Tokens) for API authentication with support for token refresh and blacklisting.

Obtaining Tokens

Request

POST /api/auth/jwt/token/
Content-Type: application/json

{
  "username": "user@example.com",
  "password": "your-password"
}

Response

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Using Access Tokens

Include the access token in the Authorization header:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://api.yourdomain.com/api/organizations/

Token Refresh

Access tokens expire after 15 minutes. Use the refresh token to obtain a new access token:

POST /api/auth/jwt/token/refresh/
Content-Type: application/json

{
  "refresh": "YOUR_REFRESH_TOKEN"
}

Token Blacklisting

Logout by blacklisting the refresh token:

POST /api/auth/jwt/token/blacklist/
Content-Type: application/json

{
  "refresh": "YOUR_REFRESH_TOKEN"
}

API Endpoints

Cloud Console API (Platform-Level)

These endpoints manage platform-wide resources like organizations, users, sites, and permissions. They use the /api/cloud/ prefix.

Organizations

GET    /api/cloud/organizations/                    # List organizations
POST   /api/cloud/organizations/                    # Create organization
GET    /api/cloud/organizations/{slug}/             # Get organization details
PUT    /api/cloud/organizations/{slug}/             # Update organization
DELETE /api/cloud/organizations/{slug}/             # Delete organization
GET    /api/cloud/organizations/{slug}/privileges/  # Get your permissions

Organization Members

GET    /api/cloud/organizations/{slug}/members/              # List members
POST   /api/cloud/organizations/{slug}/members/              # Add member
GET    /api/cloud/organizations/{slug}/members/{username}/   # Get member details
PUT    /api/cloud/organizations/{slug}/members/{username}/   # Update member
DELETE /api/cloud/organizations/{slug}/members/{username}/   # Remove member
POST   /api/cloud/organizations/{slug}/members/{username}/make_admin/    # Make admin
POST   /api/cloud/organizations/{slug}/members/{username}/remove_admin/  # Remove admin

Organization Invitations

GET    /api/cloud/organizations/{slug}/invitations/           # List invitations
POST   /api/cloud/organizations/{slug}/invitations/           # Send invitation
GET    /api/cloud/organizations/{slug}/invitations/{uuid}/    # Get invitation details
DELETE /api/cloud/organizations/{slug}/invitations/{uuid}/    # Cancel invitation
POST   /api/cloud/organizations/{slug}/invitations/{uuid}/resend/  # Resend email

Public Invitations (No Auth Required)

GET    /api/cloud/invitations/{token}/details/      # View invitation details
POST   /api/cloud/invitations/{token}/accept/       # Accept invitation

Sites (Tenants)

GET    /api/cloud/sites/                            # List all accessible sites
GET    /api/cloud/organizations/{slug}/sites/       # List organization sites
POST   /api/cloud/organizations/{slug}/sites/       # Create site
GET    /api/cloud/sites/{slug}/                     # Get site details
PUT    /api/cloud/sites/{slug}/                     # Update site
DELETE /api/cloud/sites/{slug}/                     # Delete site
GET    /api/cloud/sites/{slug}/privileges/          # Get your permissions

Domains

GET    /api/cloud/sites/{slug}/domains/             # List site domains
POST   /api/cloud/sites/{slug}/domains/             # Add domain
GET    /api/cloud/sites/{slug}/domains/{domain}/    # Get domain details
PUT    /api/cloud/sites/{slug}/domains/{domain}/    # Update domain
DELETE /api/cloud/sites/{slug}/domains/{domain}/    # Delete domain

Users

GET    /api/cloud/users/                            # List users
POST   /api/cloud/users/                            # Create user
GET    /api/cloud/users/{username}/                 # Get user details
PUT    /api/cloud/users/{username}/                 # Update user
DELETE /api/cloud/users/{username}/                 # Delete user (soft)

Groups

GET    /api/cloud/groups/                           # List groups
POST   /api/cloud/groups/                           # Create group
GET    /api/cloud/groups/{id}/                      # Get group details
PUT    /api/cloud/groups/{id}/                      # Update group
DELETE /api/cloud/groups/{id}/                      # Delete group

Permissions

GET    /api/cloud/permissions/                      # List all permissions
GET    /api/cloud/permissions/?model=site           # Filter by model
GET    /api/cloud/permissions/{id}/                 # Get permission details

Tenant-Level Endpoints

These endpoints are available on tenant subdomains and operate within the tenant's isolated environment.

Secret Types

GET    /api/secret-types/                           # List secret types
POST   /api/secret-types/                           # Create secret type
GET    /api/secret-types/{slug}/                    # Get secret type
PUT    /api/secret-types/{slug}/                    # Update secret type
DELETE /api/secret-types/{slug}/                    # Delete secret type

Secrets

GET    /api/secrets/                                # List secrets
POST   /api/secrets/                                # Create secret
GET    /api/secrets/{key}/                          # Get secret (supports inheritance)
PUT    /api/secrets/{key}/                          # Update secret
DELETE /api/secrets/{key}/                          # Delete secret
GET    /api/secrets/{key}/history/                  # Get audit history

Profile Management

GET    /api/profile/                                # Get current user profile
PUT    /api/profile/                                # Update profile
POST   /api/profile/change-password/                # Change password

Request/Response Format

Content Types

All API endpoints accept and return JSON data:

Content-Type: application/json
Accept: application/json

Standard Response Format

Success Response

{
  "id": 1,
  "name": "Example Organization",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

List Response

{
  "count": 25,
  "next": "https://api.example.com/api/organizations/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Organization 1",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Error Response

{
  "error": "Invalid request",
  "detail": "This field is required.",
  "code": "required"
}

HTTP Status Codes

Code	Description
200	OK - Request successful
201	Created - Resource created successfully
204	No Content - Request successful, no content returned
400	Bad Request - Invalid request data
401	Unauthorized - Authentication required
403	Forbidden - Permission denied
404	Not Found - Resource not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error

Pagination

List endpoints support pagination with configurable page sizes:

Query Parameters

GET /api/organizations/?page=2&page_size=20

Response

{
  "count": 150,
  "next": "https://api.example.com/api/organizations/?page=3&page_size=20",
  "previous": "https://api.example.com/api/organizations/?page=1&page_size=20",
  "results": [...]
}

Pagination Controls

page: Page number (default: 1)
page_size: Items per page (default: 20, max: 100)

Filtering and Searching

Many endpoints support filtering and searching:

Query Parameters

# Filter by status
GET /api/organizations/?is_active=true

# Search by name
GET /api/organizations/?search=acme

# Multiple filters
GET /api/organizations/?is_active=true&created_at__gte=2024-01-01

# Ordering
GET /api/organizations/?ordering=-created_at

Common Filter Fields

is_active: Boolean status filter
created_at__gte: Date greater than or equal
created_at__lte: Date less than or equal
search: Text search across relevant fields
ordering: Sort by field (prefix with - for descending)

Rate Limiting

The API implements rate limiting to prevent abuse:

Default Limits

Authenticated Users: 1000 requests per hour
Anonymous Users: 100 requests per hour
Burst Protection: 10 requests per minute

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642608000

Rate Limit Exceeded

{
  "error": "Rate limit exceeded",
  "detail": "Too many requests. Please try again later.",
  "retry_after": 3600
}

Error Handling

The API uses consistent error formatting across all endpoints:

Validation Errors

{
  "error": "Validation failed",
  "details": {
    "name": ["This field is required."],
    "email": ["Enter a valid email address."]
  }
}

Permission Errors

{
  "error": "Permission denied",
  "detail": "You do not have permission to perform this action."
}

Not Found Errors

{
  "error": "Not found",
  "detail": "Organization with id 999 does not exist."
}

CORS Configuration

The API supports Cross-Origin Resource Sharing (CORS) for web applications:

Allowed Origins

# Development
CORS_ALLOWED_ORIGINS = [
    "http://localhost:3000",
    "http://127.0.0.1:3000",
]

# Production - configure as needed
CORS_ALLOWED_ORIGINS = [
    "https://app.yourdomain.com",
]

API Versioning

Currently, Taruvi uses URL-based versioning:

# Current version (v1)
GET /api/organizations/

# Future versions
GET /api/v2/organizations/

Version changes will be documented and backward compatibility maintained where possible.

Examples

Complete Authentication Flow

# 1. Obtain tokens
curl -X POST https://api.yourdomain.com/api/auth/jwt/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "admin@example.com", "password": "password"}'

# Response: {"access": "...", "refresh": "..."}

# 2. Use access token
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://api.yourdomain.com/api/organizations/

# 3. Refresh when expired
curl -X POST https://api.yourdomain.com/api/auth/jwt/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "YOUR_REFRESH_TOKEN"}'

Creating an Organization

curl -X POST https://api.yourdomain.com/api/organizations/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "description": "Leading provider of innovative solutions",
    "subscription_plan": "enterprise"
  }'

Tenant-Specific Requests

# Switch to tenant subdomain for tenant-specific operations
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://acme.yourdomain.com/api/users/

# Or use development setup
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     http://acme.127.0.0.1.nip.io:8000/api/users/

Ready to start using the API? Check out the interactive documentation or explore specific endpoint details in our API reference.

Base URLs​

API Documentation​

Interactive Documentation​

Example URLs​

Authentication​

Obtaining Tokens​

Using Access Tokens​

Token Refresh​

Token Blacklisting​

API Endpoints​

Cloud Console API (Platform-Level)​

Organizations​

Organization Members​

Organization Invitations​

Public Invitations (No Auth Required)​

Sites (Tenants)​

Domains​

Users​

Groups​

Permissions​

Tenant-Level Endpoints​

Secret Types​

Secrets​

Profile Management​

Request/Response Format​

Content Types​

Standard Response Format​

HTTP Status Codes​

Pagination​

Filtering and Searching​

Rate Limiting​

Error Handling​

CORS Configuration​

API Versioning​

Examples​

Complete Authentication Flow​

Creating an Organization​

Tenant-Specific Requests​