API Documentation

Welcome to the Admin API reference. 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: All API requests should be made to the following endpoint. SDKs handle this automatically.

https://api.admin.io/v3

Authentication

The Admin API uses Bearer Token authentication. You can generate API keys from your Dashboard Settings. Keep your keys secure and never expose them in client-side code.

Authorization: Bearer sk_live_51J83k2k3j2k3j2k3j2k3j2k

Rate Limits

API requests are limited to 1,000 requests per minute per API key. When you exceed this limit, the API will return a 429 Too Many Requests response. Implement exponential backoff in your retry logic.

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Users Endpoint

Manage user accounts, permissions, and team assignments.

GET /users

Returns a paginated list of all users in your workspace.

Query Parameters

Name	Type	Description
limit	integer	Number of results (1-100). Default: 20
offset	integer	Pagination cursor. Default: 0
role	string	Filter by role: `admin`, `editor`, `viewer`
status	string	Filter by status: `active`, `pending`, `disabled`

curl -X GET "https://api.admin.io/v3/users?limit=10&role=admin" \n  -H "Authorization: Bearer sk_live_..."

{
  "data": [
    {
      "id": "usr_8f7a6b5c4d3e",
      "name": "Sarah Chen",
      "email": "sarah@example.com",
      "role": "admin",
      "status": "active",
      "created_at": "2024-08-12T09:30:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 10,
    "offset": 0
  }
}

POST /users

Create a new user and send an invitation email.

Name	Type	Required	Description
email	string	Yes	Valid email address
name	string	Yes	Full display name
role	string		Default: `viewer`

{
  "email": "mike@example.com",
  "name": "Mike Ross",
  "role": "editor"
}

Error Handling

Admin uses standard HTTP status codes to indicate success or failure. Errors are returned in a consistent JSON format.

Code	Meaning	Resolution
400	Bad Request	Check request body and parameters
401	Unauthorized	Verify API key format and validity
403	Forbidden	Insufficient permissions for this resource
404	Not Found	Resource ID or endpoint does not exist
429	Rate Limited	Slow down requests. Check retry-after header
500	Server Error	Internal issue. Contact support if persistent

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is expired or malformed.",
    "status": 401,
    "request_id": "req_9f8e7d6c5b4a"
  }
}

SDKs & Libraries

We maintain official SDKs for popular languages. Community-maintained libraries are also available.

Package Managers:
npm install @admin/sdk-node
pip install admin-python
go get github.com/admin-io/admin-go