Skip to main content

Activate Trusted Device

Individual API

Activate a trusted device using the activation token received during MFA verification.

Description​

The Activate Trusted Device endpoint allows users to mark a device as trusted after successfully completing MFA verification. When a device is activated, it can bypass Multi-Factor Authentication challenges on future logins, providing a streamlined authentication experience while maintaining security.

This endpoint is part of the Trusted Devices API workflow and is typically called immediately after completing MFA verification when the user chooses to "remember this device" for future logins.

Use Cases​

  • Streamlined Authentication: Users can activate frequently used devices to skip MFA challenges on subsequent logins
  • Security Management: Users can selectively trust devices they use regularly while maintaining MFA protection on new or untrusted devices
  • User Experience: Reduces friction for legitimate users while maintaining strong security posture

Workflow Context​

This endpoint is typically used in the following authentication workflow:

  1. User logs in with credentials via Login
  2. If MFA is enabled, user completes MFA Verification
  3. MFA verification response includes an activation_token if device activation is available
  4. User calls this endpoint to activate the device (optional)
  5. Future logins from this device can bypass MFA challenges

Prerequisites​

  • User must be authenticated with a valid access token
  • User must have completed MFA verification and received an activation token
  • Activation token must be valid and not expired (5-minute window)

Endpoint​

POST /api/v1/devices/activate

Headers​

HeaderRequiredDescription
AuthorizationYesBearer <access_token>
Content-TypeYesapplication/json

Request Body​

{
  "activation_token": "token_received_from_mfa_verify"
}

Parameters​

FieldTypeRequiredDescription
activation_tokenstringYesActivation token received from MFA verification response. This token is generated when MFA verification is successful and device activation is available. The token expires after 5 minutes for security purposes.

Response​

Success (200)​

{
  "success": true,
  "data": {
    "device_id": 789,
    "device_name": "Chrome on Windows",
    "activated_at": "2024-01-01T12:00:00Z",
    "expires_at": null
  },
  "message": "Device activated successfully"
}

Error Codes​

StatusCodeDescription
400INVALID_ACTIVATION_TOKENThe activation token is invalid, malformed, or has already been used. Ensure you're using the token from the most recent MFA verification response.
401UNAUTHORIZEDInvalid or missing authentication token. Ensure you include a valid Bearer token in the Authorization header.
404DEVICE_NOT_FOUNDThe device entry associated with the activation token was not found. This may occur if the device entry was already processed or removed.
410ACTIVATION_WINDOW_EXPIREDThe activation token has expired. Activation tokens are valid for 5 minutes after generation. You must complete a new MFA verification to receive a new activation token.

For more information on error handling, see Error Handling.

Features​

  • Token Validation: Validates the activation token against the device entry created during MFA verification
  • Time Window Enforcement: Enforces a 5-minute expiration window for activation tokens to prevent unauthorized device activation
  • Device Trust Activation: Marks the device as trusted, allowing it to bypass MFA challenges on future logins
  • Security Validation: Verifies device fingerprint and ensures the activation request originates from the same device that completed MFA
  • Audit Logging: Records device activation events for security monitoring and compliance

Response Fields​

FieldTypeDescription
device_idintegerUnique identifier for the activated device. Use this ID to revoke the device if needed.
device_namestringHuman-readable name for the device, typically derived from user agent and system information
activated_atstring (ISO 8601)Timestamp when the device was activated
expires_atstring (ISO 8601) or nullExpiration timestamp for device trust. If null, the device remains trusted indefinitely until manually revoked.

Activation Window​

Activation tokens expire after 5 minutes from creation. This security measure ensures that device activation must occur immediately after MFA verification. If the token expires, you must complete a new MFA verification to receive a new activation token.

The 5-minute window balances security with user experience, allowing sufficient time for the activation request while preventing potential abuse of stale tokens.

Example​

curl -X POST https://api.rivergen.com/api/v1/devices/activate \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "activation_token": "abc123def456"
  }'
  • MFA Verify - Complete MFA verification to receive activation token (prerequisite)
  • List Devices - View all trusted devices for your account
  • Revoke Device - Remove device trust if the device is lost or compromised
  • Skip Activation - Skip device activation if you prefer not to trust this device

See Also​