Attach a device

Links a device to a user. Call this function in all key views in your project. See when to call the attach function for details.

Parameters

Client ID _^REQUIRED

The string client ID of your project's API key.

User/Account _^REQUIRED

This parameter is deprecated on the Javascript SDK, use account parameter instead.

The ID of the user you want the device to be linked to. This can be the ID of the user in your own DB, or a custom generated user ID specifically for Rupt. Regardless, this ID must be saved in your DB and unique to each user.

Secret

The signed token for this user. Use this if and only if you are following the advanced security guide.

Default: undefined

Redirect URLs

This parameter is available on the Javascript SDK only.

See listen to events for more details.

groups

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

Default: undefined

id _^REQUIRED

The unique string identifier representing the group. This can be the ID of the group in your own DB, or a custom generated group ID specifically for Rupt. Regardless, this ID must be saved in your DB and unique to each group.

name

The string name/label for the group. This could be the company name or team belonging to the user.

Default: undefined

metadata

A key-value object that will be stored. This is useful if you want to store additional data.

Default: undefined

Suspended URL

This parameter is deprecated on the Javascript SDK, use redirect_urls.suspend_url parameter instead.

The URL to redirect the user to if their account is suspended. If no URL is provided and the user is suspended, the user will be redirected to a page hosted by Rupt. The hosted page includes your projects branding and can be customized on the dashboard.

Default: undefined

Metadata

A key-value object that will be stored. This is useful if you want to store additional data. This will be available in all webhooks touching this object.

Default: undefined

Debug

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.

Default: false

Include Page

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.

Only available on the Javascript SDK. (as include_page)

Limit Config

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. If the blocking dialog is not enabled, this value is ignored.

Default: {} (empty object)

Event

A string that can used to pass an event key.

Default undefined

On Challenge

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

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.

Default: undefined

const { device_id } = await Rupt.attach({
  client_id: string;
  account: string;
  secret?: string;
  redirect_urls: {
    new_account_url: string;
    logout_url: string;
    success_url: string;
    suspended_url?: string;
    upgrade_url?: string;
  };
  group: {
    id: string;
    name?: string;
    metadata?: object;
  };
  metadata?: object;
  debug?: boolean;
  include_page?: boolean;
  limit_config?: object;
  event?: "sign_up" | "trial_started" | "upgrade" | string;
  on_challenge?: () => boolean;
  on_limit_exceeded?: () => void;
  on_current_device_logout?: ({ challenge?: string }) => boolean
});