Rapid7 User Management API Guide

Auth method: API Key (X-Api-Key header)

Setup steps

1. Log in to the Rapid7 Insight Platform at insight.rapid7.com.
2. Navigate to Settings > API Keys.
3. Click 'New User Key' or 'New Organization Key' depending on scope needed.
4. Copy the generated API key; it is shown only once.
5. Include the key in all API requests as the HTTP header: X-Api-Key: .

Required scopes

List Users

• Method: GET
• URL: https://{region}.api.insight.rapid7.com/vm/v4/users
• Watch out for: InsightVM API v3 uses /api/3/users; the Insight Platform API uses a different base URL and versioning. Confirm which product API you are targeting.

Request example

GET /vm/v4/users?index=0&size=100
X-Api-Key: <org_api_key>

Response example

{
  "data": [{"id":1,"login":"jdoe","email":"jdoe@example.com"}],
  "metadata": {"index":0,"size":100,"totalPages":1,"totalResources":1}
}

Get User

• Method: GET
• URL: https://{host}:3780/api/3/users/{id}
• Watch out for: InsightVM on-premise API uses Basic Auth and a host:port URL, not the cloud Insight Platform API key pattern.

Request example

GET /api/3/users/42
Authorization: Basic <base64_credentials>

Response example

{
  "id": 42,
  "login": "jdoe",
  "email": "jdoe@example.com",
  "enabled": true,
  "locked": false,
  "role": {"id": "user", "superuser": false}
}

Create User

• Method: POST
• URL: https://{host}:3780/api/3/users
• Watch out for: Password is required for 'normal' authentication type. LDAP/SAML users do not require a password field.

Request example

POST /api/3/users
Content-Type: application/json
{
  "login":"jdoe","password":"S3cur3!",
  "name":{"first":"Jane","last":"Doe"},
  "email":"jdoe@example.com",
  "role":{"id":"user","superuser":false}
}

Response example

{
  "id": 42,
  "links": [{"href":"/api/3/users/42","rel":"self"}]
}

Update User

• Method: PUT
• URL: https://{host}:3780/api/3/users/{id}
• Watch out for: PUT replaces the full user object; omitting optional fields may reset them to defaults.

Request example

PUT /api/3/users/42
Content-Type: application/json
{
  "login":"jdoe",
  "email":"jdoe_new@example.com",
  "role":{"id":"auditor","superuser":false}
}

Response example

{
  "links": [{"href":"/api/3/users/42","rel":"self"}]
}

Delete User

• Method: DELETE
• URL: https://{host}:3780/api/3/users/{id}
• Watch out for: Deleting a user is permanent. Disable the account (enabled=false) via PUT if soft-deactivation is preferred.

Request example

DELETE /api/3/users/42
Authorization: Basic <base64_credentials>

Response example

{
  "links": [{"href":"/api/3/users","rel":"Users"}]
}

Unlock User

• Method: DELETE
• URL: https://{host}:3780/api/3/users/{id}/lock
• Watch out for: Uses DELETE method to remove the lock state, which is non-intuitive.

Request example

DELETE /api/3/users/42/lock
Authorization: Basic <base64_credentials>

Response example

{
  "links": [{"href":"/api/3/users/42","rel":"self"}]
}

Update User Password

• Method: PUT
• URL: https://{host}:3780/api/3/users/{id}/password
• Watch out for: Request body is a plain JSON string (quoted password), not a JSON object.

Request example

PUT /api/3/users/42/password
Content-Type: application/json
"NewP@ssw0rd!"

Response example

{
  "links": [{"href":"/api/3/users/42","rel":"self"}]
}

Get User Site Access

• Method: GET
• URL: https://{host}:3780/api/3/users/{id}/sites
• Watch out for: Only relevant when accessAllSites is false; returns empty if user has global site access.

Request example

GET /api/3/users/42/sites
Authorization: Basic <base64_credentials>

Response example

{
  "resources": [{"id":1,"name":"Corp Network"}],
  "page": {"number":0,"size":10,"totalResources":1}
}

• Rate limits: Rapid7 Insight Platform API rate limits are not explicitly published in official documentation as of the research date.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: Official docs do not specify rate limit values, headers, or retry behavior. Contact Rapid7 support for current limits.

• Pagination method: offset

• Default page size: 100

• Max page size: 500

• Pagination pointer: page and size (InsightVM API v3); index and size parameters used in paginated responses

• Webhooks available: No

• Webhook notes: Rapid7 Insight Platform and InsightVM do not expose a native webhook system for user management events in official documentation.

• Alternative event strategy: Use polling against the /api/3/users endpoint or leverage Insight Connect (SOAR) workflows to trigger actions on user-related events.

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• Rapid7 Insight Platform does not natively expose a SCIM 2.0 endpoint for automated user provisioning as of the research date.
• SSO via SAML is supported but SCIM provisioning is not documented as a native feature.
• Third-party IdP connectors (Okta, Azure AD) may offer limited attribute sync but not full SCIM lifecycle management.

Three automation scenarios are well-supported by the documented API.

First, provisioning a site-restricted InsightVM user requires a POST to /api/3/users with accessAllSites explicitly set to false, followed by a separate POST to /api/3/users/{id}/sites

omitting the explicit false flag causes site assignments to be silently ignored.

Second, soft-deactivating a departed employee without destroying audit history requires a GET-then-PUT pattern: retrieve the full user object, set enabled: false, and PUT the complete object back, since partial PATCH updates are not supported and omitted fields reset to defaults.

Third, unlocking a locked account uses DELETE on /api/3/users/{id}/lock an HTTP DELETE with no request body, which is semantically non-standard and may be blocked by HTTP clients configured to reject bodyless DELETEs.

Provision a new InsightVM user with site-restricted access

1. POST /api/3/users with login, password, name, email, role (id: 'user'), and accessAllSites: false.
2. Capture the returned user id from the response.
3. POST /api/3/users/{id}/sites with the array of site IDs to grant access.
4. Verify with GET /api/3/users/{id}/sites that the correct sites are listed.

Watch out for: If accessAllSites is true on the user object, explicit site assignments are ignored. Ensure accessAllSites is explicitly set to false during creation.

Disable a departed employee without deleting their audit history

1. GET /api/3/users to find the user's numeric id by login or email.
2. GET /api/3/users/{id} to retrieve the full current user object.
3. PUT /api/3/users/{id} with the full user object modified to set enabled: false.
4. Confirm with GET /api/3/users/{id} that enabled is now false.

Watch out for: PUT requires the complete user object. Sending only {enabled: false} will overwrite other fields with defaults. Always fetch first, then modify and PUT.

Unlock a locked-out user account

1. GET /api/3/users to locate the user id.
2. Confirm locked: true via GET /api/3/users/{id}.
3. Send DELETE /api/3/users/{id}/lock to remove the lock.
4. Optionally PUT /api/3/users/{id}/password to reset the password if credentials were compromised.

Watch out for: The unlock operation uses HTTP DELETE on the /lock sub-resource, not a PATCH or PUT. Ensure your HTTP client is not blocking DELETE requests with a body.

The most consequential API caveat is the full-replacement PUT behavior: there is no PATCH endpoint for user updates, so any automation that sends a partial object will silently overwrite unspecified fields with defaults, including role assignments and site access flags.

Rate limits are not publicly documented, which means production integrations must implement exponential backoff defensively rather than reactively. SCIM 2.0 is not natively available, so identity graph synchronization cannot rely on standardized provisioning events;

polling /api/3/users on a defined interval is the documented alternative to webhooks, which are also absent from the platform's user management surface. The password field is write-only and never returned in GET responses, which affects any reconciliation logic that attempts to validate authentication configuration state.