WordPress User Management API Guide

Auth method: Application Passwords (HTTP Basic Auth) for programmatic access; Cookie + Nonce for browser-based requests; OAuth 2.0 via third-party plugins (e.g., WP OAuth Server)

Setup steps

1. Ensure WordPress 5.6+ is installed (Application Passwords are built-in).
2. Log in as an admin and navigate to Users > Profile.
3. Scroll to 'Application Passwords', enter a name, and click 'Add New Application Password'.
4. Copy the generated password (shown only once).
5. Encode credentials as Base64: base64(':').
6. Include header in requests: Authorization: Basic .
7. For OAuth 2.0, install a plugin such as 'WP OAuth Server' and configure client credentials separately.

Required scopes

List Users

• Method: GET
• URL: /wp/v2/users
• Watch out for: Without authentication, only publicly visible users (those with published posts) are returned, and sensitive fields (email, roles) are omitted.

Request example

GET /wp-json/wp/v2/users?per_page=10&page=1
Authorization: Basic <base64_credentials>

Response example

[
  {
    "id": 1,
    "name": "Jane Doe",
    "slug": "janedoe",
    "email": "jane@example.com",
    "roles": ["administrator"]
  }
]

Get Current User

• Method: GET
• URL: /wp/v2/users/me
• Watch out for: Returns 401 if request is unauthenticated.

Request example

GET /wp-json/wp/v2/users/me
Authorization: Basic <base64_credentials>

Response example

{
  "id": 5,
  "username": "janedoe",
  "email": "jane@example.com",
  "roles": ["editor"],
  "registered_date": "2023-01-15T10:00:00"
}

Get Single User

• Method: GET
• URL: /wp/v2/users/{id}
• Watch out for: Non-admin users can only retrieve their own full record; fetching another user's private fields requires edit_users capability.

Request example

GET /wp-json/wp/v2/users/5
Authorization: Basic <base64_credentials>

Response example

{
  "id": 5,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "roles": ["editor"]
}

Create User

• Method: POST
• URL: /wp/v2/users
• Watch out for: Requires administrator role (create_users capability). username cannot be changed after creation.

Request example

POST /wp-json/wp/v2/users
Authorization: Basic <base64_credentials>
Content-Type: application/json

{"username":"newuser","email":"new@example.com","password":"Str0ng!","roles":["subscriber"]}

Response example

{
  "id": 12,
  "username": "newuser",
  "email": "new@example.com",
  "roles": ["subscriber"]
}

Update User

• Method: POST
• URL: /wp/v2/users/{id}
• Watch out for: WordPress REST API uses POST (not PATCH/PUT) for updates to existing resources. Changing roles requires edit_users capability.

Request example

POST /wp-json/wp/v2/users/12
Authorization: Basic <base64_credentials>
Content-Type: application/json

{"first_name":"New","roles":["editor"]}

Response example

{
  "id": 12,
  "first_name": "New",
  "roles": ["editor"]
}

Delete User

• Method: DELETE
• URL: /wp/v2/users/{id}
• Watch out for: The 'reassign' query parameter (ID of another user) is REQUIRED to reassign the deleted user's posts; omitting it returns a 400 error.

Request example

DELETE /wp-json/wp/v2/users/12?reassign=1
Authorization: Basic <base64_credentials>

Response example

{
  "deleted": true,
  "previous": {
    "id": 12,
    "username": "newuser"
  }
}

List Users with Role Filter

• Method: GET
• URL: /wp/v2/users?roles=editor
• Watch out for: The 'roles' filter requires administrator authentication; unauthenticated or non-admin requests ignore this parameter.

Request example

GET /wp-json/wp/v2/users?roles=editor&per_page=20
Authorization: Basic <base64_credentials>

Response example

[
  {
    "id": 7,
    "name": "Bob Smith",
    "roles": ["editor"]
  }
]

Get User by Slug

• Method: GET
• URL: /wp/v2/users?slug={slug}
• Watch out for: Returns an array even for a single match. Returns empty array if user has no published posts and request is unauthenticated.

Request example

GET /wp-json/wp/v2/users?slug=janedoe
Authorization: Basic <base64_credentials>

Response example

[
  {
    "id": 5,
    "slug": "janedoe",
    "name": "Jane Doe"
  }
]

• Rate limits: WordPress core does not impose REST API rate limits natively. Rate limiting depends on hosting infrastructure, server-level configuration, or plugins (e.g., Jetpack, WP REST API Rate Limit). WordPress VIP enforces platform-level rate limits.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: No standard rate-limit response headers are emitted by WordPress core. Hosts may return HTTP 429 with a Retry-After header at the server/CDN layer.
• Pagination method: offset
• Default page size: 10
• Max page size: 100
• Pagination pointer: page / per_page

• Webhooks available: No
• Webhook notes: WordPress core does not provide native outbound webhooks for user management events. There is no built-in mechanism to push notifications on user creation, update, or deletion.
• Alternative event strategy: Use WordPress action hooks (e.g., user_register, profile_update, delete_user) in custom plugin code to trigger outbound HTTP requests, or install a plugin such as WP Webhooks or Uncanny Automator to configure webhook delivery for user events.

• SCIM available: No
• SCIM version: Not documented
• Plan required: No native SCIM support in WordPress core or WordPress VIP. SCIM provisioning requires a third-party plugin (e.g., 'SCIM User Provisioning' plugins) or custom development.
• Endpoint: Not documented

Limitations:

• No native SCIM 2.0 endpoint in WordPress core.
• WordPress VIP does not provide a managed SCIM endpoint.
• SCIM support requires a third-party plugin or custom REST API extension.
• Plugin-based SCIM implementations vary in compliance and supported operations.

Provisioning a new account: POST /wp-json/wp/v2/users with username, email, password, and roles in the request body. The username field is immutable after creation - there is no rename operation via the REST API. Capture the returned id immediately for all subsequent operations.

Role promotion: Resolve the user's numeric ID first via GET /wp-json/wp/v2/users?slug={slug} (returns an array even for a single match), then POST /wp-json/wp/v2/users/{id} with the updated roles array. WordPress supports one primary role per user; sending multiple roles may result in only the last value being applied, depending on version and installed plugins. Note that WordPress uses POST - not PATCH or PUT - for updates to existing user records.

Deprovisioning: DELETE /wp-json/wp/v2/users/{id}?reassign={reassign_user_id}. The reassign parameter is mandatory; omitting it returns a 400 error. Deletion is permanent - WordPress core has no soft-delete or deactivation concept at the API layer. All Application Passwords issued to the deleted user are invalidated immediately, breaking any REST API or XML-RPC integrations that relied on those credentials.

Pagination uses offset-based paging via page and per_page parameters; default page size is 10, maximum is 100. The context query parameter (view, embed, edit) controls field visibility - edit context requires authentication and surfaces sensitive fields including email and capabilities.

Provision a new subscriber account

1. Authenticate with Application Password credentials for an administrator account.
2. POST /wp-json/wp/v2/users with body: {username, email, password, roles: ['subscriber']}.
3. Capture the returned 'id' field for future reference.
4. Optionally PATCH additional meta fields (first_name, last_name) via a follow-up POST /wp-json/wp/v2/users/{id}.

Watch out for: username is immutable after creation. Ensure the desired username is correct before submitting; there is no rename operation via the REST API.

Promote a user from subscriber to editor

1. Authenticate as an administrator.
2. GET /wp-json/wp/v2/users?slug={slug} to resolve the user's numeric ID.
3. POST /wp-json/wp/v2/users/{id} with body: {roles: ['editor']}.
4. Verify the response contains 'roles': ['editor'].

Watch out for: WordPress supports only one primary role per user. Sending multiple roles in the array may result in only the last role being applied depending on the WordPress version and any role-management plugins installed.

Deprovision (delete) a user and reassign their content

1. Authenticate as an administrator.
2. Identify the target user ID and the ID of the user who will receive reassigned content.
3. DELETE /wp-json/wp/v2/users/{id}?reassign={reassign_user_id}.
4. Confirm response contains 'deleted': true.

Watch out for: The 'reassign' parameter is mandatory. If the reassign target user ID does not exist or is invalid, the API returns a 400 error. There is no soft-delete or deactivation concept in WordPress core; deletion is permanent.

WordPress has no native SCIM 2.0 endpoint in core or on WordPress VIP. Any identity graph built on top of WordPress user data must be assembled through the REST API with administrator credentials, with no standardized provisioning protocol on the receiving end.

Plugin-based SCIM implementations exist but vary significantly in compliance, supported operations, and maintenance cadence - none are managed or guaranteed by Automattic.

Webhooks for user lifecycle events (creation, update, deletion) are also absent from core. Outbound notifications require either custom plugin code using WordPress action hooks (user_register, profile_update, delete_user) or a third-party automation plugin. This means any pipeline that needs to react to user changes in near-real-time must poll the API or maintain its own event infrastructure.

For teams building identity graph integrations - where WordPress user state needs to stay synchronized with a directory, IdP, or downstream SaaS - the absence of SCIM and native webhooks means the integration layer carries the full burden of consistency, error handling, and reconciliation.

Budget for that complexity explicitly before committing to a WordPress-native provisioning architecture.