API Reference

Welcome to the Admin API documentation. The API is designed around RESTful principles and uses standard HTTP response codes, authentication, and verbs. All requests must be made over HTTPS. Calls made over plain HTTP will fail.

Base URL: https://api.admin.io/v1
Content-Type: application/json
Authentication: Bearer Token via Authorization header

All responses are returned in JSON format. Dates are formatted according to ISO 8601 standards. For complete examples and quick start guides, visit our developer portal.

Authentication

The Admin API uses Bearer tokens for authentication. You can generate API keys from your dashboard settings. Include your API key in the Authorization header of every request.

curl -X GET "https://api.admin.io/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

⚠️ Security Notice: Never expose your API keys in client-side code or public repositories. Use environment variables or secret managers to store credentials securely.

Rate Limits

API requests are rate limited to ensure fair usage and system stability. Current limits are:

Free Tier: 100 requests/minute
Professional: 1,000 requests/minute
Enterprise: 5,000 requests/minute (custom limits available)

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: 1678901234
Retry-After: 45

Endpoints

Below are the core API endpoints available in the Admin platform. Each endpoint includes request/response examples and parameter documentation.

GET /users

Returns a paginated list of all users in your organization. Supports filtering, sorting, and field selection.

Parameter	Type	Required	Description
`page`	integer	Optional	Page number for pagination (default: 1)
`limit`	integer	Optional	Number of results per page (default: 20, max: 100)
`role`	string	Optional	Filter by role: `admin`, `editor`, `viewer`

// Response Example (200 OK)
{
  "data": [
    {
      "id": "usr_8x92mfk1",
      "name": "Sarah Reynolds",
      "email": "sarah@example.com",
      "role": "admin",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 42,
    "total_pages": 3
  }
}

POST /users

Creates a new user account in your organization. Sends an invitation email to the provided address.

Parameter	Type	Required	Description
`name`	string	Required	Full name of the user (2-100 characters)
`email`	string	Required	Valid email address for the user
`role`	string	Optional	User role. Defaults to `viewer`

{
  "name": "Marcus Kim",
  "email": "marcus@company.io",
  "role": "editor"
}

GET /dashboard/metrics

Retrieves real-time dashboard metrics and performance indicators for your workspace.

{
  "active_users": 1248,
  "revenue_mrr": 84320,
  "conversion_rate": 0.042,
  "system_health": "optimal",
  "last_updated": "2024-11-20T14:22:00Z"
}

PUT /settings

Updates global workspace settings. Requires admin role. Partial updates are supported.

Error Handling

Admin uses standard HTTP status codes to indicate the success or failure of an API request. All error responses include a consistent JSON structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format provided",
    "field": "email",
    "details": {"hint": "Email must contain @ and valid domain"}
  }
}

Common Status Codes

Code	Meaning	Description
`200`	OK	Request succeeded
`400`	Bad Request	Invalid parameters or malformed JSON
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Internal platform error