Skip to main content

Revoke Trusted Device

Individual API

Remove trust from a specific device, preventing future trusted logins.

Description​

The Revoke Trusted Device endpoint removes the trusted status from a specific device, requiring MFA verification for all future logins from that device. This is a critical security endpoint that allows users to immediately revoke device trust when a device is lost, stolen, or compromised.

This endpoint is part of the Trusted Devices API and should be used proactively for security management. Once a device is revoked, it will no longer be able to bypass MFA challenges, and the user will need to complete full authentication including MFA for any future logins from that device.

Use Cases​

  • Security Response: Immediately revoke access when a device is lost or stolen
  • Device Management: Remove trust from devices that are no longer in use
  • Security Audit: Revoke suspicious or unauthorized devices identified in the device list
  • Access Control: Manage which devices can bypass MFA verification

Workflow Context​

This endpoint is typically used:

  • After reviewing the list of trusted devices
  • When a device is lost, stolen, or suspected of being compromised
  • During security audits to remove unused or old devices
  • When rotating trusted devices for security best practices

Prerequisites​

  • User must be authenticated with a valid access token
  • User must know the device ID (obtainable from List Devices)
  • Device must exist and belong to the authenticated user

Endpoint​

DELETE /api/v1/devices/{device_id}

Headers​

HeaderRequiredDescription
AuthorizationYesBearer <access_token>

Path Parameters​

ParameterTypeRequiredDescription
device_idintegerYesUnique identifier of the device to revoke. You can obtain device IDs from the List Devices endpoint.

Response​

Success (200)​

{
  "success": true,
  "data": {
    "success": true
  },
  "message": "Device revoked successfully"
}

Error Codes​

StatusCodeDescription
401UNAUTHORIZEDInvalid or missing authentication token. Ensure you include a valid Bearer token in the Authorization header.
404DEVICE_NOT_FOUNDThe specified device ID was not found or does not belong to the authenticated user. Verify the device ID using the List Devices endpoint.

For more information on error handling, see Error Handling.

Features​

  • Immediate Revocation: Removes device trust status immediately upon successful request
  • MFA Re-enforcement: Future logins from the revoked device will require full MFA verification
  • Security Audit Logging: All revocation events are logged for security monitoring and compliance
  • User Verification: Ensures only the device owner can revoke their own devices
  • Idempotent Operation: Revoking an already-revoked device returns success without error

Important Security Notes​

  • Immediate Effect: Device revocation takes effect immediately. The device cannot bypass MFA on the next login attempt.
  • No Recovery: Once revoked, the device cannot be automatically re-trusted. The user must complete a new MFA verification and activate the device again.
  • Session Impact: Revoking a device does not invalidate existing sessions. To terminate active sessions, use the Sessions API.

Example​

curl -X DELETE https://api.rivergen.com/api/v1/devices/789 \
  -H "Authorization: Bearer <access_token>"
  • List Devices - View all trusted devices to identify device IDs (prerequisite)
  • Activate Device - Re-activate a device after revocation if needed
  • Revoke Session - Terminate active sessions from a compromised device

See Also​