Navigation

Attach a device

Attach a device to a user.

Parameters

client_id string REQUIRED

The client ID of your project's API key.

user / account string REQUIRED

The ID of the user you want the device to be linked to. user is deprecated.

redirect_urls object

The URLs to redirect the user to after certain events in the challenge. For more information, please see the challenges documentation.

Child parameters
redirect_urls.logout_url string

The redirect url used when a device is detached.

redirect_urls.new_account_url string

The redirect url used when a new account cta is pressed.

redirect_urls.success_url string

The redirect url used when the challenge is completed.

redirect_urls.suspended_url string

The redirect url used when the suspension is determinded for an attached device

redirect_urls.upgrade_url string

The redirect url used when a updgrade account cta is pressed


groups object / array of objects

The group or groups that the user belongs to. This can be a group object or an array of group objects.

Child parameters
group.id string REQUIRED

The id of the group in your system.

group.name string

The name of the group or organization.

group.metadata object

The custom metadata to be appended to any pre-existing group metadata.


metadata object

The custom metadata to be appended to any pre-existing device metadata.

include_page boolean

A boolean that, if set to true, will automatically get the page (URL on the web) and send it with the access data. This will then be shown with each access on the dashboard.

signals object

A set of browser signals that will be used to identify the device. Use the getSignals method from the Rupt SDK. Refer to the Rupt SDK for more information.

limit_config object

An object that allows you to override the settings of the project default limits. This can be useful if you want to set the limit for each individual user depending on his or her plan. It supports multiple properties, but the only one that is currently active is: limit_config.overall_limit which controls the overall device limit and does not differentiate between mobile and desktop. Leave this undefined if you want to rely on the dashboard configuration.

Child parameters
limit_config.overall_device_limit number

The overall device limit for the user.

limit_config.people_limit number

The limit of people that can be attached to the user.


event string

A string that can be used to pass an event key.

on_challenge function

A callback that is triggered when Rupt determines that a particular device session should be challenged. If this callback returns false, the challenge will not be shown. This callback is only available on the Javascript SDK.

on_current_device_logout function

A function that's called whenever the current device needs to be detached. This can happen in one of two scenarios:

  • The user was shown the dialog and select to log out of this device. Keep in mind, the user could be asking to log out this device from another device where the dialog is presented. Or they can select to log out of the same device. In both cases, the function is called.
  • You manually call detach and passed the device ID of a specific device. If the device with that ID implements this callback and it's online, it will be immediately called.

It is strongly recommended that you implement this callback. Inside this callback, you should immediately log the user out of your application.

on_limit_exceeded function

A function that's called when the user exceeds the specified device limit.

debug boolean

A boolean indicating whether to run in debug mode or not. If debug is true, any errors will be printed to the console as well as warnings and recommendations.


Returns

Returns device and user access state information.
POST /v2/device/attach
import { attach } from 'rupt';

const { device_id } = await attach({
  client_id: "CLIENT_ID",
  account: "account_id",
  metadata: { key: "value" },
  groups: [{ 
    id: "group_id", 
    name: "group_name", 
    metadata: { key: "value" } 
  }],
})
Response
{ 
  "success": true,
  "attached_devices": 3,
  "device_id": "6323dadac7c49192e9154563",
  "default_device_limit": 2,
  "block_over_usage": false,
}