API Documentation

Welcome to the Admin API reference. Our RESTful API allows you to integrate seamlessly with the Admin platform. All requests must be made over HTTPS. Calls made over plain HTTP will fail.

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

Authentication

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

Request Header

1Authorization: Bearer sk_live_4f6b2c9d8e7a1b3f5d0c9e8a7b6c5d4e

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

Users

Retrieve a paginated list of users in your organization.

GET /users

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Results per page (default: 20, max: 100)
`role`	string	No	Filter by role: `admin`, `editor`, `viewer`
`status`	string	No	Filter by status: `active`, `suspended`

Response Example

JSON
{
  "data": [
    {
      "id": "usr_9x2k4m8p",
      "name": "Alex Morgan",
      "email": "alex@admin.co",
      "role": "admin",
      "created_at": "2024-11-15T08:30:00Z"
    }
  ],
  "meta": { "total": 142, "page": 1 }
}

Create User

Provision a new user account in your organization.

POST /users

Body Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Full name of the user
`email`	string	Yes	Unique email address
`role`	string	Yes	Initial role assignment
`department`	string	No	Department identifier

Error Handling

Admin uses standard HTTP status codes to indicate success or failure. Codes in the 2xx range indicate success. Codes in the 4xx range indicate client errors. Codes in the 5xx range indicate server errors.

200 OK

Request succeeded

201 Created

Resource created successfully

400 Bad Request

Invalid parameters

401 Unauthorized

Missing or invalid token

403 Forbidden

Insufficient permissions

404 Not Found

Resource does not exist

Error Response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'email' field is required.",
    "status": 400
  }
}