NextUI Identity Admin API Specification

Overview

NextUI Identity Admin API is a standardized REST API specification that allows third-party applications to be managed by the NextUI Admin Platform. By implementing this API, any application can expose user, role, and tenant management capabilities in a consistent way.

Version: 1.0.0 Base Path: /admin Content-Type: application/json

Authentication

All API endpoints require authentication using Bearer Token:

Authorization: Bearer <access_token>

The access token should be obtained through your application's authentication flow (e.g., OAuth2, API Key exchange, etc.).

Required Scopes

• admin:users:read - Read user information
• admin:users:write - Create, update, delete users
• admin:roles:read - Read role information
• admin:roles:write - Create, update, delete roles
• admin:tenants:read - Read tenant information (if multi-tenant)

Common Models

PagedResult

{
  "items": [],
  "totalCount": 100,
  "pageIndex": 0,
  "pageSize": 20,
  "totalPages": 5
}

ErrorResponse

{
  "code": "USER_NOT_FOUND",
  "message": "User with ID 'abc123' was not found.",
  "details": {}
}

User

{
  "id": "string",
  "username": "string",
  "email": "string",
  "emailVerified": true,
  "firstName": "string",
  "lastName": "string",
  "displayName": "string",
  "avatarUrl": "string",
  "enabled": true,
  "roles": ["admin", "user"],
  "attributes": {
    "department": "Engineering",
    "title": "Software Engineer"
  },
  "tenantId": "string",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "lastLoginAt": "2024-01-01T00:00:00Z"
}

CreateUserRequest

{
  "username": "string (required)",
  "email": "string (required)",
  "firstName": "string",
  "lastName": "string",
  "password": "string",
  "temporaryPassword": true,
  "enabled": true,
  "roles": ["user"],
  "attributes": {},
  "tenantId": "string"
}

UpdateUserRequest

{
  "email": "string",
  "firstName": "string",
  "lastName": "string",
  "displayName": "string",
  "avatarUrl": "string",
  "enabled": true,
  "attributes": {}
}

Role

{
  "id": "string",
  "name": "string",
  "displayName": "string",
  "description": "string",
  "permissions": ["users:read", "users:write"],
  "isSystem": false,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

CreateRoleRequest

{
  "name": "string (required)",
  "displayName": "string",
  "description": "string",
  "permissions": []
}

UpdateRoleRequest

{
  "displayName": "string",
  "description": "string",
  "permissions": []
}

Tenant

{
  "id": "string",
  "name": "string",
  "displayName": "string",
  "domain": "string",
  "enabled": true,
  "settings": {},
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

User Management Endpoints

GET /admin/users

Get a paginated list of users.

Query Parameters:

Response: 200 OK

{
  "items": [
    {
      "id": "user-001",
      "username": "john.doe",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "displayName": "John Doe",
      "enabled": true,
      "roles": ["admin", "user"],
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "totalCount": 150,
  "pageIndex": 0,
  "pageSize": 20,
  "totalPages": 8
}

POST /admin/users

Create a new user.

Request Body: CreateUserRequest

{
  "username": "jane.smith",
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "password": "SecureP@ssword123",
  "temporaryPassword": true,
  "enabled": true,
  "roles": ["user"]
}

Response: 201 Created

{
  "id": "user-002",
  "username": "jane.smith",
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "displayName": "Jane Smith",
  "enabled": true,
  "roles": ["user"],
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Responses:

• 400 Bad Request - Invalid request body
• 409 Conflict - Username or email already exists

GET /admin/users/

Get a user by ID.

Path Parameters:

Response: 200 OK

{
  "id": "user-001",
  "username": "john.doe",
  "email": "john.doe@example.com",
  "emailVerified": true,
  "firstName": "John",
  "lastName": "Doe",
  "displayName": "John Doe",
  "avatarUrl": "https://example.com/avatars/john.jpg",
  "enabled": true,
  "roles": ["admin", "user"],
  "attributes": {
    "department": "Engineering"
  },
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-10T15:20:00Z",
  "lastLoginAt": "2024-01-14T09:00:00Z"
}

Error Responses:

• 404 Not Found - User not found

PUT /admin/users/

Update a user.

Path Parameters:

Request Body: UpdateUserRequest

{
  "firstName": "Jonathan",
  "lastName": "Doe",
  "displayName": "Jonathan Doe",
  "enabled": true,
  "attributes": {
    "department": "Engineering",
    "title": "Senior Engineer"
  }
}

Response: 200 OK

Returns the updated user object.

Error Responses:

• 400 Bad Request - Invalid request body
• 404 Not Found - User not found
• 409 Conflict - Email already in use

DELETE /admin/users/

Delete a user.

Path Parameters:

Response: 204 No Content

Error Responses:

• 404 Not Found - User not found
• 409 Conflict - Cannot delete (e.g., last admin user)

GET /admin/users/

Get roles assigned to a user.

Path Parameters:

Response: 200 OK

{
  "userId": "user-001",
  "roles": [
    {
      "id": "role-001",
      "name": "admin",
      "displayName": "Administrator"
    },
    {
      "id": "role-002",
      "name": "user",
      "displayName": "User"
    }
  ]
}

Error Responses:

• 404 Not Found - User not found

PUT /admin/users/

Set roles for a user (replaces all existing roles).

Path Parameters:

Request Body:

{
  "roleIds": ["role-001", "role-002"]
}

Or by role names:

{
  "roleNames": ["admin", "user"]
}

Response: 200 OK

Returns the updated user roles.

Error Responses:

• 400 Bad Request - Invalid role IDs/names
• 404 Not Found - User not found

POST /admin/users/

Set or reset a user's password.

Path Parameters:

Request Body:

{
  "password": "NewSecureP@ssword123",
  "temporary": true
}

Response: 204 No Content

Error Responses:

• 400 Bad Request - Password does not meet requirements
• 404 Not Found - User not found

Role Management Endpoints

GET /admin/roles

Get a list of all roles.

Query Parameters:

Response: 200 OK

{
  "items": [
    {
      "id": "role-001",
      "name": "admin",
      "displayName": "Administrator",
      "description": "Full system access",
      "permissions": ["*"],
      "isSystem": true,
      "createdAt": "2024-01-01T00:00:00Z"
    },
    {
      "id": "role-002",
      "name": "user",
      "displayName": "User",
      "description": "Standard user access",
      "permissions": ["profile:read", "profile:write"],
      "isSystem": true,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "totalCount": 2
}

POST /admin/roles

Create a new role.

Request Body: CreateRoleRequest

{
  "name": "moderator",
  "displayName": "Moderator",
  "description": "Can moderate content",
  "permissions": ["content:read", "content:moderate"]
}

Response: 201 Created

{
  "id": "role-003",
  "name": "moderator",
  "displayName": "Moderator",
  "description": "Can moderate content",
  "permissions": ["content:read", "content:moderate"],
  "isSystem": false,
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Responses:

• 400 Bad Request - Invalid request body
• 409 Conflict - Role name already exists

GET /admin/roles/

Get a role by ID.

Path Parameters:

Response: 200 OK

Returns the role object.

Error Responses:

• 404 Not Found - Role not found

PUT /admin/roles/

Update a role.

Path Parameters:

Request Body: UpdateRoleRequest

{
  "displayName": "Content Moderator",
  "description": "Can moderate and approve content",
  "permissions": ["content:read", "content:moderate", "content:approve"]
}

Response: 200 OK

Returns the updated role object.

Error Responses:

• 400 Bad Request - Invalid request body or cannot modify system role
• 404 Not Found - Role not found

DELETE /admin/roles/

Delete a role.

Path Parameters:

Response: 204 No Content

Error Responses:

• 400 Bad Request - Cannot delete system role
• 404 Not Found - Role not found
• 409 Conflict - Role is in use

Tenant Management Endpoints (Optional)

These endpoints are optional and should only be implemented if your application supports multi-tenancy.

GET /admin/tenants

Get a list of all tenants.

Query Parameters:

Response: 200 OK

{
  "items": [
    {
      "id": "tenant-001",
      "name": "acme-corp",
      "displayName": "ACME Corporation",
      "domain": "acme.example.com",
      "enabled": true,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "totalCount": 5,
  "pageIndex": 0,
  "pageSize": 20,
  "totalPages": 1
}

Server Info Endpoint

GET /admin/info

Get information about the server and its capabilities.

Response: 200 OK

{
  "name": "My Application",
  "version": "1.0.0",
  "apiVersion": "1.0.0",
  "features": {
    "users": true,
    "roles": true,
    "tenants": false,
    "passwordReset": true,
    "userAttributes": true
  },
  "limits": {
    "maxUsersPerPage": 100,
    "maxRolesPerUser": 50
  }
}

Error Codes

Implementation Notes

For Application Developers

1. Implement the interface: Implement IStandardAdminApi in your application
2. Use the controller base: Extend StandardAdminControllerBase for quick implementation
3. Register endpoints: Map the controller to /admin path
4. Add authentication: Protect endpoints with appropriate authentication middleware

For NextUI Admin Platform

The platform will:

1. Discover the server using GET /admin/info
2. Use the features object to determine available capabilities
3. Call the appropriate endpoints based on user actions
4. Handle errors gracefully based on error codes

CORS Configuration

If your API will be accessed from a browser-based admin panel, ensure CORS is configured:

builder.Services.AddCors(options =>
{
    options.AddPolicy("AdminPanel", policy =>
    {
        policy.WithOrigins("https://admin.nextui.dev")
              .AllowAnyMethod()
              .AllowAnyHeader()
              .AllowCredentials();
    });
});

Versioning

The API uses URL versioning. Future versions will be available at:

• /admin/v1/users (current, v1 is optional)
• /admin/v2/users (future)

Clients should check the apiVersion field in /admin/info response.