Admin API Reference

Programmatic access to Admin's platform. Build integrations, automate workflows, and manage resources at scale.

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

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

Authentication

Authenticate your API requests by including your API key in the Authorization header using the Bearer scheme.

Authorization: Bearer sk_live_51H8k3jL2mN9pQ4rS7tU0vW2xY3zA6bC

Keep your API keys secure. Never expose them in client-side code or public repositories.

Error Handling

Admin uses conventional HTTP status codes to indicate success or failure.

Code	Meaning	Description
`400`	Bad Request	The request was invalid or cannot be served.
`401`	Unauthorized	Your API key is missing or invalid.
`404`	Not Found
`429`	Rate Limited
`500`	Server Error

Users

GET /users

Retrieve a list of all users. Returns users sorted by creation date, newest first.

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 20, max: 100)
status	string	Filter by status: `active`, `invited`, `suspended`

{
  "data": [
    {
      "id": "usr_9f8e7d6c5b4a",
      "email": "developer@example.com",
      "name": "Alex Morgan",
      "role": "admin",
      "created_at": "2024-11-15T08:30:00Z"
    }
  ],
  "meta": { "total": 142, "page": 1 }
}

POST /users

Create a new user in your organization.

Parameter	Type	Description
email	string	Required. Valid email address
name	string	Required. Full display name
role	string	Default: `viewer`. Options: `admin`, `editor`, `viewer`

{
  "id": "usr_1a2b3c4d5e6f",
  "email": "newuser@company.io",
  "name": "Jordan Lee",
  "role": "editor",
  "created_at": "2024-12-01T14:22:00Z"
}

Organizations

GET /organizations/{org_id}

Fetch details for a specific organization by its unique identifier.

{
  "id": "org_x7y9z2a3b4c5",
  "name": "Acme Corp",
  "domain": "acme.com",
  "plan": "enterprise",
  "billing_status": "active",
  "limits": { "users": 500, "storage_gb": 1000 }
}

Webhooks

POST /webhooks

Register a webhook endpoint to receive real-time event notifications.

Parameter	Type	Description
url	string	Required. HTTPS endpoint to receive payloads
events	array	List of event types to subscribe to
secret	string	Used to verify webhook signatures

{
  "id": "wh_8g7f6e5d4c3b",
  "url": "https://hooks.example.com/admin",
  "events": ["user.created", "org.updated", "billing.failed"],
  "active": true,
  "created_at": "2024-11-20T09:15:00Z"
}

Rate Limits

API requests are limited to 1,000 requests per minute per API key. When exceeded, the API returns a 429 Too Many Requests response with a Retry-After header indicating seconds to wait.

Monitor your usage via the X-RateLimit-Remaining and X-RateLimit-Reset headers on every response.