🔄 Update User Status API

This API allows enterprise applications to update the status of a user in the REL-ID system. It supports lifecycle transitions like BLOCK, DELETE, RESET, etc., and follows specific business rules for allowable state changes.

🔗 Endpoint

PUT https://REL-ID-SERVER-IP:9442/v1/users/{userId}/status

🔐 Authorization

Authorization: Bearer <access_token>
Content-Type: application/json

🔧 Path Parameter

Parameter	Required	Description
`userId`	✅ Yes	REL-ID user ID whose status is to be updated

📥 Request Body

{
  "status": "<NEW_STATUS>",
  "comments": "optional comment"
}

Field	Required	Description
`status`	✅ Yes	New status to apply. See table below.
`comments`	❌ Optional	Optional comment for maker/checker audit trail. Appears in Admin Activity Report.

🔤User Status explained

Status	Meaning
`CREATED`	User has been created but is not yet activated. No authentication allowed.
`ONBOARDING`	Used during identity verification (IDV) onboarding workflows. User can be transitioned to CREATED or DELETED.
`ACTIVE`	User is fully onboarded and can authenticate normally.
`BLOCKED`	User is temporarily blocked and cannot authenticate. When user tries to attempt, to login with erroneous credentials for more than the permitted number of attempts, the user will be moved to BLOCKED state. User can be blocked by GM admin from GM
`PAUSED`	User is paused — typically used when user is re-verifying identity or put on hold. User will not be allowed to do any operation using REL-ID integrated App.
`RESET`	User is force reset — login credentials and tokens are invalidated. Requires reactivation.
`UNBLOCK`	Special transition to remove the BLOCKED state.
`UNPAUSE`	Special transition to remove the PAUSED state.
`DELETED`	Soft deletes the user — login or authentication is not possible. User data retained.
`INACTIVE`	A user may transition to the INACTIVE state if they have not accessed any REL-ID–integrated application for a pre-configured duration. While in this state, the user is restricted from performing any operations through REL-ID–enabled applications.

🧾 Status Values and Transition Rules

This table summarizes the allowed input values for status, what they do, the final state of the user, and which previous statuses they are valid from:

Input Status	Action Performed	Final Status	Valid From Statuses
`BLOCK`	Temporarily disables the user from authentication or login. Typically used for temporary suspensions.	`BLOCKED`	`CREATED`, `ACTIVE`, `RESET`
`UNBLOCK`	Lifts the BLOCKED status and transitions the user back to ACTIVE. Restores ability to authenticate.	`ACTIVE`	`BLOCKED`
`RESET`	Invalidates login credentials and keys. Triggers re-onboarding.	`RESET`	`ACTIVE`, `BLOCKED`, `PAUSED`, `DELETED`
`DELETE`	Soft deletes the user. Authentication is disabled, but data is retained for audit.	`DELETED`	`CREATED`, `ACTIVE`, `BLOCKED`, `RESET`, `PAUSED`, `ONBOARDING`
`PAUSE`	Temporarily suspends user during IDV flows or pending review. Access to services is disabled.	`PAUSED`	`CREATED`, `ACTIVE`, `RESET`
`UNPAUSE`	Lifts PAUSE and restores user to ACTIVE status ( or user's previous state before user had got paused )	`ACTIVE`	`PAUSED`
`CREATE`	Finalizes onboarding and moves user to CREATED. Used when transitioning from IDV onboarding.	`CREATED`	`ONBOARDING`

🧾 Example Request

PUT /v1/users/abc1/status
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "BLOCK",
  "comments": "Blocking due to suspicious activity"
}

✅ Success Response

HTTP 200 OK

❌ Failure Responses

HTTP Code	Scenario	Message Example
`404`	User does not exist	`"User does not exist: abc"`
`422`	Invalid status, invalid transition, or malicious input in comment	`"Please update with appropriate status..."`
`400`	Invalid JSON format	`"Malformed request body"`
`500`	Internal server/database error	`"REL-ID-GEN-ERROR: DB operation failed"`

❌ Error Responses

🔍 404 - User Not Found

{
  "timeStamp": "2023-05-30T12:33:32IST",
  "status": 404,
  "error": "Data not present.",
  "message": "User does not exist: abc",
  "path": "/v1/users/abc/status"
}

⚠️ 422 - Invalid Status or Transition

{
  "timeStamp": "2023-05-30T12:33:32IST",
  "status": 422,
  "error": "Invalid data.",
  "message": "[Please update with appropriate status from BLOCK, DELETE, PAUSE, RESET, UNBLOCK, UNPAUSE, CREATE]",
  "path": "/v1/users/abc/status"
}

⛔ 422 - Transition Not Allowed

{
  "timeStamp": "2023-05-30T12:33:32IST",
  "status": 422,
  "error": "Invalid data.",
  "message": "[User status update is not allowed as user's current status is BLOCKED]",
  "path": "/v1/users/string1/status"
}

❌ 400 - Malformed Request

{
  "timeStamp": "2024-02-10T08:23:11UTC",
  "status": 400,
  "error": "Bad Request",
  "message": "Malformed request body",
  "path": "/v1/users/abc/status"
}

💥 500 - Internal Server Error

{
  "timeStamp": "2024-01-24T06:59:13UTC",
  "status": 500,
  "error": "Failed.",
  "message": "REL-ID-GEN-ERROR: DB operation failed",
  "path": "/v1/users/abc/status"
}