User Management

API endpoints for user management operations.

Learn more about User Management API.

Search for a User by Email

get

This endpoint searches for a user using an email address pattern. It supports exact matches and wildcard searches. For wildcard searches, use the * character (e.g., email=*@domain.com or email=john*@domain.com). The search is case-insensitive and can be used to find users based on partial or complete email addresses.

Use Cases

• Identify Specific Users: Retrieve user details based on an exact email match.

• Wildcard Search: Find users across an organization or group by using flexible search patterns.

• User Audit and Reporting: Verify user existence and retrieve associated metadata for system audits or reports.

---

Required Access

• API Scope: api, api-readonly

• Site Roles: Opsera Administrator, Administrator, Power User

---

Process Details

• Search Query Validation: Validates the search query format to ensure it uses the correct email pattern.

• User Lookup:

  • Retrieves all active users in the system.

  • Filters users based on the provided search query.

  • Supports both exact match and wildcard searches.

• Response Handling:

  • If a single user matches the query, returns the user data.

  • If multiple users match, prompts the client to refine the search.

  • If no users match, returns a 404 response.

---

Important Notes!

• Search Format: Use the email= prefix in the query (e.g., [email protected]).

• Wildcard Searches: Use the * character to match multiple users (e.g., email=*@opsera.io).

• Case Insensitivity: The search query is not case-sensitive.

• Multiple Matches: If more than one user matches the query, you must refine the search to a single user.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Query parameters

searchstringRequired

Search query in the format email=value. Supports exact email matches and wildcard patterns.

• Examples:
  • [email protected] (exact match)
  • email=*@opsera.io (all users in the domain)
  • email=john*@opsera.io (all users starting with "john")
  • email=*engineer*@opsera.io (all users with "engineer" in the email)

Example: [email protected]

Responses

200

Successfully retrieved user

application/json

_idstringOptional

Opsera User ID. Used as a primary key for user-related operations.

Example: 5e1cbf251c26d68f7ce6361e

applicationsstring[]Optional

List of application IDs that the user has access to. Each ID represents a specific application in the system.

Example: ["60633793310cdb13fa85afa5","608304e85d1e526c80bb9749"]

toolsstring[]Optional

List of tool IDs that the user has access to. Tools represent different functionalities or integrations available to the user.

Example: ["61eafd724868abd5193bfd4c","61f70a5b61b870001112d37c"]

firstNamestringOptional

User's first name or given name, used for identification and display purposes.

Example: John

lastNamestringOptional

User's last name or family name, used for identification and display purposes.

Example: Doe

emailstringOptional

User's email address, used for authentication and communication. Must be unique within the system.

Example: [email protected]

ssoSystemstringOptional

The Single Sign-On (SSO) system used for user authentication. Indicates how the user authenticates with the system.

Example: okta

organizationNamestringOptional

Name of the organization the user belongs to. Used for organizational context and access control.

Example: Example Inc.

divisionstringOptional

User's organizational division or department. Helps in categorizing users within the organizational structure.

Example: Engineering

domainstringOptional

The domain associated with the user's organization. Used for authentication and organization-specific features.

Example: Example Domain

createdAtstring · date-timeOptional

Timestamp indicating when the user account was created. Stored in ISO 8601 format.

Example: 2020-01-13T19:04:05.632Z

updatedAtstring · date-timeOptional

Timestamp indicating when the user account was last modified. Stored in ISO 8601 format.

Example: 2024-10-28T10:08:20.705Z

groupsstring[]Optional

List of group IDs that the user belongs to. Groups provide additional access control and organization capabilities.

activebooleanOptional

Indicates whether the user account is currently active. Inactive accounts cannot access the system.

Example: true

400

Bad request - Invalid search query or multiple users found

application/json

403

Forbidden - User doesn't have permission to search users

404

User not found

application/json

500

Internal server error

application/json

get

/api/v2/usermanagement/user

HTTPcURLJavaScriptPython

GET /api/v2/usermanagement/user?search=text HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "5e1cbf251c26d68f7ce6361e",
  "applications": [
    "60633793310cdb13fa85afa5",
    "608304e85d1e526c80bb9749"
  ],
  "tools": [
    "61eafd724868abd5193bfd4c",
    "61f70a5b61b870001112d37c"
  ],
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "ssoSystem": "okta",
  "organizationName": "Example Inc.",
  "division": "Engineering",
  "domain": "Example Domain",
  "createdAt": "2020-01-13T19:04:05.632Z",
  "updatedAt": "2024-10-28T10:08:20.705Z",
  "groups": [],
  "active": true
}

Create a New User

post

Use this endpoint to create a new user within your organization on the Opsera platform. The new user will be set up within the organization context and can be assigned specific roles and groups to define their permissions. For more details on required user permissions, refer to the Opsera User Management API documentation.

Use Cases

• Onboard new employees: Add new users to the platform, assigning them the appropriate roles and groups.

• Extend organization membership: Add users across departments or functional roles with customized access.

---

Required Access

• API Scope: api

• Site Roles: Opsera Administrator, Administrator, Power User

---

Process Details

Upon calling this endpoint:

1. The system validates the request body, including required fields and specific data formatting (e.g., email and siteRole).

2. It checks if the user already exists in both LDAP and SSO systems.

3. If not, the user is created in both systems and assigned to groups if provided.

4. The newly created user receives an email invitation for registration completion.

---

Important Notes!

• Site Role Validation: The siteRole field must be one of the specified valid roles (e.g., Administrators, PowerUsers).

• Email Format: Email addresses must follow a standard format and cannot already be registered in the organization.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Body

application/json

emailAddressstring · emailRequired

User's email address. Must be a valid email format and will be used for authentication and communication.

Example: [email protected]

firstNamestringRequired

User's first name or given name. Used for identification and display purposes throughout the system.

Example: John

lastNamestringRequired

User's last name.

Example: Doe

preferredNamestringOptional

User's preferred name or nickname. This is an optional field that can be used instead of firstName in display contexts.

Example: Johnny

titlestringOptional

User's job title or position within the organization. Helps in understanding the user's role and responsibilities.

Example: Senior Software Engineer

sitestringOptional

User's physical location or office site. Useful for organizational and administrative purposes.

Example: Headquarters

divisionstringOptional

User's organizational division or department. Helps in categorizing users within the organizational structure.

Example: Engineering

siteRolestring · enumRequired

Specifies the user's access level in the system. Must be one of:

• Administrators: Full system access and control.
• PowerUsers: Extended privileges for managing resources.
• Users: Standard access to system features.
• Auditors: Read-only access for audit purposes.
• SecurityManagers: Special security access for security-related functions.

Example: UsersPossible values:

groupsstring[]Optional

List of group IDs the user should be added to. Groups provide additional access control and organization capabilities.

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]

Responses

200

User created successfully

application/json

messagestringOptionalExample: User creation complete

400

Bad Request - Invalid input data

application/json

403

Forbidden - User lacks permission to create users

500

Internal server error

application/json

post

/api/v2/usermanagement/user

HTTPcURLJavaScriptPython

POST /api/v2/usermanagement/user HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 258

{
  "emailAddress": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "preferredName": "Johnny",
  "title": "Senior Software Engineer",
  "site": "Headquarters",
  "division": "Engineering",
  "siteRole": "Users",
  "groups": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ]
}

{
  "message": "User creation complete",
  "user": {
    "_id": "507f1f77bcf86cd799439011",
    "applications": [
      "507f1f77bcf86cd799439011",
      "507f1f77bcf86cd799439012"
    ],
    "tools": [
      "507f1f77bcf86cd799439013",
      "507f1f77bcf86cd799439014"
    ],
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "ssoSystem": "exampleSso",
    "organizationName": "text",
    "division": "Engineering",
    "domain": "example.com",
    "createdAt": "2023-11-01T12:00:00.000Z",
    "updatedAt": "2023-11-02T12:00:00.000Z",
    "groups": [],
    "active": true
  }
}

Get a Specific User by ID

get

This endpoint fetches detailed information about a specific user by their Opsera User ID. The response includes essential user attributes, organizational details, and system access information. This endpoint is commonly used to manage user records or display user details in administrative interfaces. For more details on required user permissions, refer to the Opsera User Management API documentation.

Use Cases

• Account Management: Retrieve comprehensive user details for administrative tasks such as auditing, reporting, or updates.

• Permission Verification: Validate user access to tools, applications, or organizational divisions.

• UI/UX Integration: Provide detailed user profiles in dashboards or other user-facing interfaces.

• Compliance and Auditing: Ensure organizational compliance by fetching user-related information.

---

Required Access

• API Scopes: api, api-readonly

• Site Roles: Opsera Administrator, Administrator, Power User

---

Process Details

• Parameter Validation:

  • Validates that the userId parameter is provided and is in the correct format.

  • Rejects invalid or missing userId parameters.

• User Data Retrieval:

  • Fetches user details using the userId.

  • Sanitizes sensitive properties to ensure data security.

• Response Handling:

  • Returns the sanitized user details if found.

  • Provides appropriate error messages for missing or invalid users.

---

Important Notes!

• Required Parameter: The userId must be included in the request and uniquely identify the user.

• Security Consideration: Sensitive user attributes are omitted to ensure data security.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

userIdstringRequired

The user identifier, which can be either a MongoDB ID or an email address.

• For MongoDB ID: Use the user's Opsera ID directly.
• For email: Use the user's complete email address.

Example: {"value":"6449c988b5760b001e46c27f","summary":"MongoDB ID Example"}

Responses

200

Successfully retrieved user

application/json

_idstringOptional

Opsera User ID. Used as a primary key for user-related operations.

Example: 507f1f77bcf86cd799439011

applicationsstring[]Optional

List of application IDs that the user has access to. Each ID represents a specific application in the system.

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]

toolsstring[]Optional

List of tool IDs that the user has access to. Tools represent different functionalities or integrations available to the user.

Example: ["507f1f77bcf86cd799439013","507f1f77bcf86cd799439014"]

firstNamestringOptional

User's first name or given name, used for identification and display purposes.

Example: Jane

lastNamestringOptional

User's last name or family name, used for identification and display purposes.

Example: Smith

emailstringOptional

User's email address, used for authentication and communication. Must be unique within the system.

Example: [email protected]

ssoSystemstringOptional

The Single Sign-On (SSO) system used for user authentication. Indicates how the user authenticates with the system.

Example: exampleSso

organizationNamestringOptional

Name of the organization the user belongs to. Used for organizational context and access control.

Example: Example Corporation

divisionstringOptional

User's organizational division or department. Helps in categorizing users within the organizational structure.

Example: Engineering

domainstringOptional

The domain associated with the user's organization. Used for authentication and organization-specific features.

Example: company.example.com

createdAtstring · date-timeOptional

Timestamp indicating when the user account was created. Stored in ISO 8601 format.

Example: 2023-11-01T12:00:00.000Z

updatedAtstring · date-timeOptional

Timestamp indicating when the user account was last modified. Stored in ISO 8601 format.

Example: 2023-11-02T12:00:00.000Z

groupsstring[]Optional

List of group IDs that the user belongs to. Groups provide additional access control and organization capabilities.

activebooleanOptional

Indicates whether the user account is currently active. Inactive accounts cannot access the system.

Example: true

400

Bad request - Invalid user ID

application/json

403

Forbidden - User doesn't have permission to view user details

404

User not found

application/json

500

Internal server error

application/json

get

/api/v2/usermanagement/user/{userId}

HTTPcURLJavaScriptPython

GET /api/v2/usermanagement/user/{userId} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "507f1f77bcf86cd799439011",
  "applications": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ],
  "tools": [
    "507f1f77bcf86cd799439013",
    "507f1f77bcf86cd799439014"
  ],
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "ssoSystem": "exampleSso",
  "organizationName": "Example Corporation",
  "division": "Engineering",
  "domain": "company.example.com",
  "createdAt": "2023-11-01T12:00:00.000Z",
  "updatedAt": "2023-11-02T12:00:00.000Z",
  "groups": [],
  "active": true
}

Deactivate a User in the System

delete

This endpoint deactivates a user account by setting the user's active status to false, rather than permanently deleting the record. This approach ensures the user's data, history, and associations are preserved for auditing purposes or potential future reactivation. This is ideal for managing inactive users while maintaining data integrity and historical traceability. For more details on required user permissions, refer to the Opsera User Management API documentation.

Use Cases

• User Offboarding: Temporarily deactivate accounts for employees or contractors who leave the organization but may return later.

• Access Control Management: Suspend users who no longer require access to the system without erasing historical activity.

• Data Retention: Retain user records for auditing or compliance purposes while preventing further system access.

---

Required Access

• API Scopes: api

• Site Roles: Opsera Administrator, Administrator

---

Process Details

• Parameter Validation:

  • Ensures that a valid userId is provided in the request.

  • Rejects the request if the userId is missing or invalid.

• Deactivation Process:

  • Calls the backend service to set the active status of the user to false.

• Response Handling:

  • Returns a success message if the deactivation is completed successfully.

  • Responds with appropriate error messages for invalid input or unexpected issues.

---

Important Notes!

• Non-Destructive Operation: This is a soft delete. The user record remains in the system and can be reactivated later.

• Required Parameter: The userId must be provided and must uniquely identify the user.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

userIdstringRequired

The user identifier, which can be either a MongoDB ID or an email address.

• For MongoDB ID: Use the user's Opsera ID directly.
• For email: Use the user's complete email address.

Example: {"value":"507f1f77bcf86cd799439011","summary":"MongoDB ID Example"}

Responses

200

User deactivated successfully.

application/json

messagestringOptional

Confirmation message indicating the user was deactivated.

Example: User deactivation completed: true

400

Bad Request - Invalid user ID or deactivation failed.

application/json

403

Forbidden - User doesn't have permission to deactivate users.

422

Unprocessable Entity - Missing required parameters.

application/json

500

Internal Server Error.

application/json

delete

/api/v2/usermanagement/user/{userId}

HTTPcURLJavaScriptPython

DELETE /api/v2/usermanagement/user/{userId} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "User deactivation completed: true"
}

Assign Site Role to a User

patch

Use this endpoint to update or assign a site role to an existing user within your organization on the Opsera platform. The site role determines the user's access level and permissions within the system.

Use Cases

• Role Promotion/Demotion: Change a user's access level based on job responsibilities.

• Access Management: Assign appropriate permissions to users based on their organizational role.

• Onboarding Updates: Modify initial role assignments after user creation.

---

Environment Availability

Important: This endpoint is only available in QA environments (development, staging, testing). It is not available in production environments.

---

Process Details

Upon calling this endpoint:

1. The system validates the request body, including the required userId and siteRole fields.

2. The user identifier is resolved (supports both MongoDB ID and email address).

3. The site role is validated against the allowed roles.

4. The user's site role is updated in the system.

---

Important Notes!

• Site Role Validation: The siteRole field must be one of the specified valid roles.

• User Identification: The userId can be either a MongoDB ID or an email address.

• QA Only: This endpoint is restricted to non-production environments.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Body

application/json

userIdstringRequired

The user identifier, which can be either a MongoDB ID or an email address.

• For MongoDB ID: Use the user's Opsera ID directly.
• For email: Use the user's complete email address.

Example: {"value":"507f1f77bcf86cd799439011","summary":"MongoDB ID Example"}

siteRolestring · enumRequired

Specifies the user's access level in the system. Must be one of:

• Administrators: Full system access and control.
• PowerUsers: Extended privileges for managing resources.
• Users: Standard access to system features.
• Auditors: Read-only access for audit purposes.
• SecurityManagers: Special security access for security-related functions.

Example: PowerUsersPossible values:

Responses

200

Site role updated successfully

application/json

messagestringOptional

Confirmation message indicating the site role was updated.

Example: Successfully updated site role for user.

400

Bad Request - Missing or invalid parameters

application/json

404

Not Found - User not found

application/json

500

Internal Server Error

application/json

patch

/api/v2/usermanagement/user/site-role

HTTPcURLJavaScriptPython

PATCH /api/v2/usermanagement/user/site-role HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "userId": "text",
  "siteRole": "PowerUsers"
}

{
  "message": "Successfully updated site role for user.",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "organizationName": "Example Corporation",
    "active": true
  }
}

Get Active Users (search by email or IDs)

get

This endpoint returns only active users matching the search criteria. Supports both email pattern matching and ID-based lookup. It is useful for retrieving multiple users at once, either by searching their email addresses or by providing a list of specific user IDs. For more details, refer to the Opsera API Documentation.

Use Cases

• Retrieve active users by email pattern (e.g., all users from a specific domain).

• Fetch specific users by their unique IDs.

• Integrate with external systems that require user information based on email or ID.

---

Required Access

• API Scope: api, api-readonly

• Site Roles: Opsera Administrator, Administrator, Power User

---

Process Details

• Email Search:

  • Supports wildcard patterns using the * character.

  • Case-insensitive matching.

  • Example searches:

    • email=*@company.com (all users with company.com email addresses).

    • email=user* (all users whose email starts with user).

    • email=*name*@company.com (all users with name in their email at company.com).

• ID-based Lookup:

  • Provide a comma-separated list of user IDs.

  • Only returns active users with the specified IDs.

  • Maintains the order of users as per input IDs.

---

Important Notes!

• If both search and id parameters are provided, the id parameter takes precedence.

• The endpoint returns only active users; inactive users are excluded.

• Input parameters are sanitized to prevent injection attacks.

• Sensitive fields are omitted from the response for security reasons.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Query parameters

searchstringOptional

Search query for user emails. Supports wildcard patterns using the * character.

• Examples:
  • email=*@company.com (all users with company.com addresses)
  • email=user* (all users whose email starts with 'user')
  • email=*name*@company.com (all users with 'name' in their email at company.com)

idstringOptional

Comma-separated list of user IDs to retrieve specific users.

• Example: id=507f1f77bcf86cd799439011,507f1f77bcf86cd799439012,507f1f77bcf86cd799439013
• Note: Only active users with the specified IDs will be returned.

Responses

200

Successfully retrieved active users

application/json

Array of user objects matching the search criteria

_idstringOptional

Unique identifier for the user in database format. Used as a primary key for user-related operations.

Example: 507f1f77bcf86cd799439011

applicationsstring[]Optional

List of application IDs that the user has access to. Each ID represents a specific application in the system.

Example: ["60633793310cdb13fa85afa5","608304e85d1e526c80bb9749"]

toolsstring[]Optional

List of tool IDs that the user has access to.

Example: ["61eafd724868abd5193bfd4c","61f70a5b61b870001112d37c"]

firstNamestringOptional

User's first name or given name, used for identification and display purposes.

Example: John

lastNamestringOptional

User's last name or family name, used for identification and display purposes.

Example: Doe

emailstringOptional

User's email address, used for authentication and communication. Must be unique within the system.

Example: [email protected]

ssoSystemstringOptional

The Single Sign-On (SSO) system used for user authentication. Indicates how the user authenticates with the system.

Example: acmeSso

organizationNamestringOptional

Name of the organization the user belongs to. Used for organizational context and access control.

Example: Company Name

divisionstringOptional

User's organizational division or department. Helps in categorizing users within the organizational structure.

Example: Engineering

domainstringOptional

The domain associated with the user's organization. Used for authentication and organization-specific features.

Example: company.com

createdAtstring · date-timeOptional

Timestamp indicating when the user account was created.

Example: 2023-11-01T12:00:00.000Z

updatedAtstring · date-timeOptional

Timestamp indicating when the user account was last modified. Stored in ISO 8601 format.

Example: 2023-11-02T12:00:00.000Z

groupsstring[]Optional

List of group IDs that the user belongs to. Groups provide additional access control and organization capabilities.

activebooleanOptional

Indicates whether the user account is currently active. Inactive accounts cannot access the system.

Example: true

400

Invalid search query or ID format

application/json

500

Internal server error

application/json

get

/api/v2/usermanagement/users

HTTPcURLJavaScriptPython

GET /api/v2/usermanagement/users HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "applications": [
      "60633793310cdb13fa85afa5",
      "608304e85d1e526c80bb9749"
    ],
    "tools": [
      "61eafd724868abd5193bfd4c",
      "61f70a5b61b870001112d37c"
    ],
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "ssoSystem": "acmeSso",
    "organizationName": "Company Name",
    "division": "Engineering",
    "domain": "company.com",
    "createdAt": "2023-11-01T12:00:00.000Z",
    "updatedAt": "2023-11-02T12:00:00.000Z",
    "groups": [],
    "active": true
  }
]