Admin API Reference

Programmatic access to your Admin workspace. Build integrations, automate workflows, and sync data.

Base URL: https://api.admin.com/v1

The Admin API uses standard HTTP methods and returns JSON payloads. All requests must be authenticated and include the appropriate content type headers. Pagination is supported via cursor-based tokens.

Authentication

Authenticate your API requests by including your secret key in the Authorization header as a Bearer token. Generate keys from your Admin Dashboard → Settings → API Keys.

curl https://api.admin.com/v1/users \\
  -H "Authorization: Bearer sk_live_9f8e7d6c5b4a3210" \\
  -H "Content-Type: application/json"

const response = await fetch('https://api.admin.com/v1/users', {
  headers: {
    'Authorization': `Bearer sk_live_9f8e7d6c5b4a3210`
  }
});

import requests

headers = {
    "Authorization": "Bearer sk_live_9f8e7d6c5b4a3210"
}
response = requests.get("https://api.admin.com/v1/users", headers=headers)

Rate Limits

API requests are limited to 1,000 requests per minute per API key. Exceeding this limit returns a 429 Too Many Requests status. Include the Retry-After header value in your backoff strategy.

Endpoints

GET /v1/users

Retrieve a paginated list of users in your workspace. Supports filtering by role, status, and search query.

Parameter	Type	Description
`limit`	integer	Number of records (default: 20, max: 100)
`cursor`	string	Pagination cursor from previous response
`role`	string	Filter by role: `admin`, `editor`, `viewer`
`status`	string	`active` or `inactive`

curl "https://api.admin.com/v1/users?limit=10&role=admin" \\
  -H "Authorization: Bearer sk_live_9f8e7d6c5b4a3210"

{
  "data": [
    {
      "id": "usr_2x9k3m4n5p",
      "name": "Jane Cooper",
      "email": "jane@example.com",
      "role": "admin",
      "status": "active",
      "created_at": "2024-11-15T08:30:00Z"
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6ICJ1c3Jf...",
    "has_more": true
  }
}

POST /v1/users

Create a new user in your workspace. An invitation email will be sent automatically unless send_invitation is set to false.

Parameter	Type	Description
`name` required	string	Full name of the user
`email` required	string	Valid email address
`role` required	string	`admin`, `editor`, or `viewer`
`send_invitation`	boolean	Default: `true`

curl https://api.admin.com/v1/users \\
  -X POST \\
  -H "Authorization: Bearer sk_live_9f8e7d6c5b4a3210" \\
  -d '{"name": "Alex Morgan", "email": "alex@company.io", "role": "editor"}'

{
  "id": "usr_8y7x6w5v4u",
  "name": "Alex Morgan",
  "email": "alex@company.io",
  "role": "editor",
  "status": "invited",
  "created_at": "2024-12-01T14:22:00Z"
}

GET /v1/audit-logs

Fetch audit trail events for compliance and debugging. Events are retained for 90 days.

Parameter	Type	Description
`action`	string	Filter by event type: `user.login`, `user.delete`, `config.update`
`user_id`	string	Filter logs by specific user
`start_time`	datetime	ISO 8601 format

Error Handling

Admin API uses standard HTTP status codes. Error responses include a machine-readable error_code and human-readable message.

200 OK - Request succeeded

201 Created - Resource created

204 No Content - Deleted successfully

400 Bad Request - Invalid parameters

401 Unauthorized - Invalid or missing API key

403 Forbidden - Insufficient permissions

404 Not Found - Resource doesn't exist

429 Too Many Requests - Rate limit exceeded

500 Internal Server Error - Try again later

Error Response Format

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "status": 401,
    "request_id": "req_8f7g6h5j4k3l2m"
  }
}

SDKs & Libraries

Official and community-maintained SDKs are available for popular languages. All SDKs handle authentication, retries, and pagination automatically.

JavaScript/Node.js: npm install @admin/api
Python: pip install admin-api
Ruby: gem install admin-ruby
Go: go get github.com/admin/api-go