Admin API Documentation

Introduction

Welcome to the Admin API documentation. Our RESTful API allows you to programmatically manage users, track analytics, configure webhooks, and integrate Admin into your existing workflows.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Base URL

https://api.admin.io/v1

Quick Example

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

import requests

response = requests.get(
  "https://api.admin.io/v1/users",
  headers={"Authorization": "Bearer sk_live_abc123"}
)
print(response.json())

const response = await fetch('https://api.admin.io/v1/users', {
  headers: { 'Authorization': 'Bearer sk_live_abc123' }
});
console.log(await response.json());

Authentication

The Admin API uses Bearer token authentication. You must include your secret API key in the `Authorization` header of every request.

Security Best Practice

Never expose your `sk_live_` keys in client-side code or public repositories. Use environment variables or a secrets manager.

Header	Value	Description
`Authorization`	`Bearer <your_api_key>`	Required. Your secret or publishable key.
`Content-Type`	`application/json`	Required for POST/PUT requests.

GET /v1/users

Returns a paginated list of all users in your workspace. Supports filtering by role, status, and creation date.

Parameters

Name	Type	Required	Description
`limit`	integer	No	Number of results per page (1-100). Default: 20
`cursor`	string	No	Pagination cursor from previous response
`role`	string	No	Filter by role: `admin`, `editor`, `viewer`
`status`	string	No	Filter by status: `active`, `suspended`, `pending`

{ "data": [ { "id": "usr_8x3k9", "name": "Alice Chen", "email": "alice@admin.io", "role": "admin" } ], "pagination": { "has_more": true, "next_cursor": "eyJpZCI6MTAyfQ" } }

POST /v1/users

Creates a new user in your workspace. An invitation email will be sent automatically if `send_invite` is true.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Full name of the user
`email`	string	Yes	Valid email address
`role`	string	No	User role. Default: `viewer`
`send_invite`	boolean	No	Send onboarding email. Default: `true`

{
  "name": "Jordan Lee",
  "email": "jordan@example.com",
  "role": "editor"
}

{ "id": "usr_9m2p1", "name": "Jordan Lee", "email": "jordan@example.com", "status": "pending", "created_at": "2025-11-02T14:30:00Z" }

PUT /v1/users/{id}

Updates an existing user's details. Only provided fields will be modified.

Path Parameter

Parameter	Type	Description
`id`	string	The unique user identifier (e.g., `usr_8x3k9`)

DELETE /v1/users/{id}

Permanently removes a user from your workspace. This action cannot be undone.

⚠️ Warning

Deleting a user revokes all active sessions, API tokens, and scheduled jobs associated with their account.

Error Codes

Admin uses standard HTTP status codes and returns detailed error objects in JSON format.

Code	Meaning	Description
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient permissions for this resource
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal processing failure

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: email",
    "doc_url": "https://docs.admin.io/errors#invalid_request"
  }
}

Rate Limits

API requests are limited to ensure fair usage. Limits are applied per API key and reset every minute.

Standard: 100 requests/minute
Pro: 1,000 requests/minute
Enterprise: Custom limits based on SLA

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating seconds to wait.