Version 2021

Manage Badges

Supports cardholder and badge management through Identity Server when a new credential is created by card adapter.

Add New Badges to Cardholders

You may create new badges for existing cardholders using this action. It takes a JSON object containing a list of (userID, cardNumber) pairs along with extra attributes such as access level, badge type, etc.

Request format

HTTP method

POST

Resource URL

/badges

Parameters

None.

Request header

Content-Type:application/json

Request body

Add badges

Copy 
{
  "actionType": "add",
  "badges": [
    {
      "userId": "alivick@microstrategy.com",
      "cardNumber":"34342"
    },
    {
      "userId": "arane@microstrategy.com",
      "cardNumber":"34343"
    }
  ]
}

Response format

Response header

content-Type:application/json

Location: /badges

Response Status Code

200 OK

Response body

Success response

Copy 
//*success message values are optional (the value of the field, field should be there at least)
{
  "json_version": "2.0",
  "actionType": "add",
  "totalUpdatedBages": 2,
  "message": "Successfully added 2 badges",
  "status": "SUCCESS",
  "badges": [
    {
      "userId": "alivick@microstrategy.com",
      "cardNumber": "34342",
      "status": "SUCCESS",
      "message": "Successfully added"
    },
    {
      "userId": "arane@microstrategy.com",
      "cardNumber": "34343",
      "status": "SUCCESS",
      "message": "Successfully added"
    }
  ]
}

Response Status Code

400 (Bad Request), 405 (Method Not Allowed), 408 (Request Timeout)

Response body

Failure response

Copy 
//ERROR is returned for the overall status if there is an overall error, such as connection problem or invalid request
//Empty request body
{
  "json_version": "2.0",
  "status": "ERROR",
  "message": "Manage badges request body is an invalid format."
}
//invalid actionType, not including the actionType field is OK
{
  "json_version": "2.0",
  "actionType": "test",
  "status": "ERROR",
  "message": "Manage badges request body is an invalid format. Invalid actionType: test"
}

Failure response for individual badge errors

Copy 
//overall status ERROR_BADGES is returned for when 1 or more (including all) of the individual badges have an ERROR
{
  "json_version": "2.0",
  "actionType": "add",
  "totalUpdatedBages": 1,
  "message": "Error adding 1 out of 2 badges",
  "status": "ERROR_BADGES",
  "badges": [
    {
      "userId": "testk@microstrategy.com",
      "cardNumber": "34342",
      "status": "ERROR",
      "message": "UserId (testk@microstrategy.com) does NOT exist."
    },
    {
      "userId": "arane@microstrategy.com",
      "cardNumber": "34345",
      "status": "SUCCESS",
      "message": "Successfully added"
    }
  ]
}
//Even if all individual badges ERROR, then overall status is ERROR_BADGES
{
  "json_version": "2.0",
  "actionType": "add",
  "totalUpdatedBages": 0,
  "message": "Error adding 2 out of 2 badges",
  "status": "ERROR_BADGES",
  "badges": [
    {
      "userId": "testk@microstrategy.com",
      "cardNumber": "34342",
      "status": "ERROR",
      "message": "UserId (testk@microstrategy.com) does NOT exist."
    },
    {
      "userId": "alivick@microstrategy.com",
      "cardNumber": "34345",
      "status": "ERROR",
      "message": "Unexpected exception during manageUserCredential: com.microstrategy.adapter.brivo.utils.BrivoAdapterException: {\"message\":\"The credential is already assigned to another user.\",\"code\":400}"
    }
  ]
}

 

Remove Badges from Cardholders

You may remove badges from existing cardholders using this action. It takes a JSON object containing a list of (userID, cardNumber) pairs.

Request format

HTTP method

POST

Resource URL

/badges

Parameters

None.

Request Header

content-Type:application/json

Request body

Remove badges

Copy 
{
  "actionType": "remove",
  "badges": [
    {
      "userId": "alivick@microstrategy.com",
      "cardNumber":"34348"
    },
    {
      "userId": "arane@microstrategy.com",
      "cardNumber":"34349"
    }
  ]
}

Response format

Response header

content-Type:application/json

Location: /badges

Response Status Code

200 OK

Response body

Remove success response

Copy 
//*success message values are optional (the value of the field, field should be there at least)
{
  "json_version": "2.0",
  "actionType": "remove",
  "totalUpdatedBages": 2,
  "message": "Successfully removed 2 badges",
  "status": "SUCCESS",
  "badges": [
    {
      "userId": "alivick@microstrategy.com",
      "cardNumber": "34348",
      "status": "SUCCESS",
      "message": "Successfully removed"
    },
    {
      "userId": "arane@microstrategy.com",
      "cardNumber": "34349",
      "status": "SUCCESS",
      "message": "Successfully removed"
    }
  ]
}

Response Status Code

400 (Bad Request), 405 (Method Not Allowed), 408 (Request Timeout)

Response body

Failure response

Copy 
//ERROR is returned for the overall status if there is an overall error, such as connection problem or invalid request
//Empty request body
{
  "json_version": "2.0",
  "status": "ERROR",
  "message": "Manage badges request body is an invalid format."
}
//invalid actionType, OK not to include actionType field
{
  "json_version": "2.0",
  "actionType": "test",
  "status": "ERROR",
  "message": "Manage badges request body is an invalid format. Invalid actionType: test"
}

Failure response for individual badge errors

Copy 
//overall status ERROR_BADGES is returned for when 1 or more (including all) of the individual badges have an ERROR
{
  "json_version": "2.0",
  "actionType": "remove",
  "totalUpdatedBages": 1,
  "message": "Error removing 1 out of 2 badges",
  "status": "ERROR_BADGES",
  "badges": [
    {
      "userId": "test@microstrategy.com",
      "cardNumber": "34348",
      "status": "ERROR",
      "message": "UserId (test@microstrategy.com) does NOT exist."
    },
    {
      "userId": "arane@microstrategy.com",
      "cardNumber": "34349",
      "status": "SUCCESS",
      "message": "Successfully removed"
    }
  ]
}
//Even if all individual badges ERROR, then overall status is ERROR_BADGES
{
  "json_version": "2.0",
  "actionType": "remove",
  "totalUpdatedBages": 0,
  "message": "Error removing 2 out of 2 badges",
  "status": "ERROR_BADGES",
  "badges": [
    {
      "userId": "test@microstrategy.com",
      "cardNumber": "34348",
      "status": "ERROR",
      "message": "UserId (test@microstrategy.com) does NOT exist."
    },
    {
      "userId": "arane@microstrategy.com",
      "cardNumber": "34349",
      "status": "ERROR",
      "message": "Unexpected exception during manageUserCredential: com.microstrategy.adapter.brivo.utils.BrivoAdapterException: {\"message\":\"Provided Credential and User are not associated\",\"code\":400}"
    }
  ]
}