BastionXP Documentation

# SCIM user API Reference

# Overview

The SCIM user API allows you to access, create, and modify user data in BastionXP.

# HTTP Headers

  • Authorization (Required): Bearer <access_token>
  • Content-Type: application/scim+json
  • Accept-Encoding: utf-8
  • Accept-Charset: utf-8

# User Attributes

You can specify user attributes in the body of the API requests as key-value pairs in JSON format. These pairs contain information about the user, such as the user’s display name or their email address.

BastionXP supports the following attributes for user lifecycle management:

SCIM User Attribute BastionXP User Attribute Type Description
id ID string Immutable unique identifier (GUID).
userName NAME, LOGIN_NAME string Identifier used to login.
name.givenName GIVEN_NAME string First name of the user.
name.familyName FAMILY_NAME string Last name of the user.
emails EMAIL string Email address.
displayName DISPLAY_NAME string Display name in UI.
externalID N/A string Unique identifier set by provisioning client.
password PASSWORD string Password (not returned in JSON response).
active DISABLED boolean Disables user when set to false.
groups N/A string List of groups (immutable).
meta.created CREATED_ON string Time user was added.
meta.resourceType N/A string Resource type (use user).
schemas N/A string Namespace URIs supported.

# Check if a user exists

# Method and endpoint:

GET /scim/v2/Users?filter=userName eq "{ { user_name } }"

# Description:

  • Returns details about a user associated with the userName query parameter.

  • Returns the HTTP response status code 200 if the HTTP request successfully completed.

# Get details about a user

# Method and endpoint:

GET /scim/v2/Users/{ { user_id } }

# Description:

  • Returns details about a user associated with the user_id path parameter.

  • Returns the HTTP response status code 200 if the HTTP request successfully completed.

# Create a user

# Method and endpoint:

POST /scim/v2/Users

# Description:

  • Creates a user in BastionXP.

  • Returns the HTTP response status code 201 if the HTTP request successfully completed.

  • If the user already exists or the HTTP request failed for a different reason, then BastionXP returns the HTTP response status code 409.

# Examples

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
  ],
  "userName": "test_user_1",
  "password": "test",
  "name": {
    "givenName": "test",
    "familyName": "user"
  },
  "emails": [
    {"value": "[email protected]"}
  ],
  "displayName": "test user",
  "active": true
}

# Replace user attributes

# Method and endpoint:

PATCH /scim/v2/Users/{ { id } }

# Description:

  • Replaces attributes of the user associated with the id path parameter.

  • You must set op to replace to perform this HTTP request.

  • active allows the following values:

    • false: deactivates the user.

    • true: activates the user.

  • Returns the HTTP response status code 200 if the HTTP request was successfully completed.

  • If unsuccessful, returns the HTTP response code 204.

# Examples

Deactivate a user and update their givenName to deactivated_user:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {"op": "replace", "value": { "active": false }}
    {"op": "replace", "value": { "givenName": "deactivated_user" }}
  ],
}

Update the user's userName to a new value.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "userName", "value": "test_updated_name"}  
  ]
}

# Update a user

# Method and endpoint:

PUT /scim/v2/Users/{ { id } }

# Description:

  • Updates the attributes of the user associated with the id path parameter.

  • If unsuccessful, returns the HTTP response code 400. The HTTP request is unsuccessful if the request tries to change immutable attributes or if the attributes being changed do not exist in BastionXP.

# Examples

Note:

The PUT method is more expensive than the PATCH method. Use the PATCH operation instead.

{
  "schemas": [
   "urn:ietf:params:scim:schemas:core:2.0:User",
  ],
  "userName": "test_user_1",
  "password": "test",
  "name": {
    "givenName": "test",
    "familyName": "user"
  },
  "emails": [{
    "primary": true,
    "value": "[email protected]",
    "type": "work"
  }
  ],
  "displayName": "test user",
  "active": true,
}

# Delete a user

# Method and endpoint:

DELETE /scim/v2/Users/{ { id } }

# Description:

Deletes the user associated with the id path parameter.

← SCIM group API reference →