Skip to main content

Class: SlashID

This class is the main entry point for users of the SlashID SDK. It exposes a single function for uniform access to all supported identification methods as id. The returned BaseUser object has methods to either register further user handles (e.g. a second e-mail address, or a phone number), or ask the user to authenticate using any number of available authentication methods. Please see BaseUser for further details and examples.

For a quick start please consult the constructor and id documentation and examples.

Constructors​

constructor​

• new SlashID(options?)

Example

For production you can simply create your SlashID instance with:

import * as slashid from "slashid"
const sid = new slashid.SlashID()

If you want to experiment and connect to the sandbox environment instead:

const sid = new slashid.SlashID({
  environment: "sandbox"
})

Throws

TypeError If the given options, if defined, fail validation

Parameters​

NameTypeDescription
options?SlashIDOptionsYour SlashID connection options.

Properties​

authnClient​

• authnClient: DefaultApi

baseURL​

• Readonly baseURL: string

credentialStorage​

• credentialStorage: CredentialsStorageV2

identifiersStorage​

• identifiersStorage: IdentifiersStorage

iframe​

• iframe: null | HTMLIFrameElement

oid​

• Optional Readonly oid: string

personsClient​

• personsClient: PersonsApi

sdkURL​

• Readonly sdkURL: string

Methods​

[PRIVATE_PUBLISH]​

▸ [PRIVATE_PUBLISH]<Key>(type, event): void

Variant of [publish] for private events

Type parameters​

NameType
Keyextends "clientSideError"

Parameters​

NameType
typeKey
eventPrivateEvents[Key]

Returns​

void

[PRIVATE_SUBSCRIBE]​

▸ [PRIVATE_SUBSCRIBE]<Key>(type, handler): void

Variant of [subscribe] for private events

Type parameters​

NameType
Keyextends "clientSideError"

Parameters​

NameType
typeKey
handlerHandler<PrivateEvents[Key]>

Returns​

void

[PRIVATE_UNSUBSCRIBE]​

▸ [PRIVATE_UNSUBSCRIBE]<Key>(type, handler): void

Variant of [subscribe] for private events

Type parameters​

NameType
Keyextends "clientSideError"

Parameters​

NameType
typeKey
handlerHandler<PrivateEvents[Key]>

Returns​

void

createAnonymousUser​

▸ createAnonymousUser(): Promise<AnonymousUser>

Returns​

Promise<AnonymousUser>

getAnalytics​

▸ getAnalytics(): BrowserAnalytics

Get an instance of the Analytics class. Use the instance to track virtual page views.

Throws

Error If analytics is not enabled or oid is not set.

Returns​

BrowserAnalytics

Analytics instance

getAvailableAuthenticationMethods​

▸ getAvailableAuthenticationMethods(handleType): Promise<FactorMethod[]>

List the available authentication methods for the chosen handle type. Currently available authentication methods are listed in FactorMethod. Before choosing a method to pass to id you should consult the result of this method. In particular the availability of the ['Webauthn'] method depends on the current device configuration and might not always be available.

It's important to note that you can rely on some authentication methods to always be available:

On the contrary, the availability of ['Webauthn'] depends exclusively on the current device configuration.

Remarks

The availability of authetication methods can vary over time, you probably should not cache or store the result and instead invoke the method any time you need to authenticate a user.

Example

SlashID supports a number of handle types, each in turn supporting a set of authentication methods. Supposing you identify your users with e-mail addresses, you should check the authentication methods available on the current device before kicking off the authentication flow:

const availableMethods = sid.getAvailableAuthenticationMethods("email_address")
// => availableMethods === ["webauthn", "email_link"]

At this point you can choose which method to use in id. You could decide based on one or a combination of:

  • Your static preference: e.g. require WebAuthn, prefer WebAuthn (['Webauthn']) if available, otherwise fallback to magic link via e-mail (['EmailLink'])
    const chosenMethod = availableMethods.includes("webauthn") ? "webauthn" : "email_link"
  • User's choice: you could present your users with a selection of the available methods;

In general the SlashID SDK does not impose any restriction on how you decide to choose which authentication method to use.

Parameters​

NameTypeDescription
handleTypePersonHandleTypeAvailable handle types are "email_address", "phone_number" and "username".

Returns​

Promise<FactorMethod[]>

An array of the available authentication methods on this device.

getAvailableIdentifiers​

▸ getAvailableIdentifiers(): Promise<PersonHandle[]>

List the handles previously used to authenticate successfully.

Remarks

Use of this method is in no way required to authenticate with SlashID. The SDK provides it to allow you to more easily implement loging suggestion drop-down lists and similar UX niceties, by e.g. tying it to a <datalist>:

const handles = await sid.getAvailableIdentifiers()
const options = handles.map((handle) => {
  const option = document.createElement("option")
  option.value = handle.value
  return option
})
const datalist = document.getElementById("available_identifiers")
datalist.replaceChildren(...options)

...

<input ... list="available_identifiers" />

Depending on browser settings, it may not be possible to discover these identifiers.

Returns​

Promise<PersonHandle[]>

An array of identifiers of previously-authenticated users.

getChallengesFromURL​

▸ getChallengesFromURL(): Promise<null | ChallengeListInner[]>

Get a Promise that resolves to an array of challenge objects.

Returns​

Promise<null | ChallengeListInner[]>

getSDKUrl​

▸ getSDKUrl(): URL

Returns​

URL

getUser​

▸ getUser(token): User

Preferred way of creating a BaseUser instance based on an existing token.

Parameters​

NameTypeDescription
tokenstringA user UserTokenText value.

Returns​

User

User instance

getUserFromURL​

▸ getUserFromURL(): Promise<null | BaseUser>

Process authentication challenges from the URL query parameters. You can use this in conjunction with the Direct-ID API to allow your users to land on your target page already authenticated.

If Identity Provider Initiated SSO is enabled and the organization ID is set, this method will also start the SSO flow given the correct parameters.

Returns​

Promise<null | BaseUser>

The authenticated user from the challenges URL parameter, if present, null otherwise.

id​

▸ id(oid, handle, authenticationFactor): Promise<User>

Identify a user. This method implements the SlashID authentication flow. In particular the flow is:

  • passwordless: all you need to specify to authenticate a user is their handle, be it an e-mail address or phone number, and how they wish to authenticate; please see the parameters documentation for more details;

  • unified: it does not require you to differentiate between first registration and subsequent logins attempts. The SlashID service takes care of the distinction and will perform the necessary verification ceremonies on your behalf under the hood.

  • synchronous: on successful return the user has verified their identity; even when the authentication spans multiple devices and is comprised of multiple steps (e.g clicking a magic link on the provided e-mail address and creating a new biometric credential on the current device), this method will not return until all steps have completed or errors have been encountered.

Before utilizing any authentication method you should check whether it is available with getAvailableAuthenticationMethods.

The currently available options for the authenticationFactor.method field are:

  • "webauthn": Authenticate the user via WebAuthn on this device. If available this usually entails built-in biometric authentication or the use of an external FIDO key, with a preference for the former. Please also see the WebAuthn scope and WebAuthn attachment sections below for details.

  • "email_link": Deliver a magic link via e-mail.

  • "otp_via_email": Deliver an OTP security code via e-mail. This authentication method requires you to publish an otpCodeSubmitted event to the SDK. The event payload must be a string containing the OTP value, which your user will receive via e-mail.

  • "sms_link": Deliver a magic link via SMS.

  • "otp_via_sms": Deliver an OTP security code via SMS. This authentication method requires you to publish an otpCodeSubmitted event to the SDK. The event payload must be a string containing the OTP value, which your user will receive via SMS.

  • oidc: Authenticate the user using OIDC through a preconfigured Identity Provider.

  • totp: Authenticate the user with a TOTP code. This authentication method requires you to publish an otpCodeSubmitted event to the SDK. The event payload must be a string containing the OTP code, which your user will retrieve from their authenticator app or device.

WebAuthn scope

In case you have chosen the WebAuthn method, you have the option to specify a scope in the options field. This field allows you to control the breadth of your users' WebAuthn credentials. The field is optional, but if specified it can either be your domain or any "registrable domain suffix" of it. E.g. if your domain is shop.domain.com you have two options to choose from:

  • shop.domain.com: scope your users to the current domain. Credentials created here will not be shared with sibling domains such as services.domain.com;
  • domain.com: scope your users to the least specific domain. Credentials created here will be allowed to access all subdomains such as services.domain.com;

Please consult the HTML spec for the formal definition of registrable domain suffix if you need detailed information. When not specified the scope option defaults to the current origin, shop.domain.com in the example above.

WebAuthn attachment

Users can perform WebAuthn either with built-in authenticators (FaceID, TouchID, fingerprint readers, etc.) or external security keys, and in case you have a preference you can control which authenticator type to use by specifying an attachment option field in the options field. The field is optional and has 3 allowed values from the WebAuthnAuthenticatorAttachment enum:

  • "platform": mandate use of built-in authenticators;
  • "cross-platform": mandate use of external security keys;
  • "any": the default value if unspecified, allows both types;

If left unspecified (or explicitly set to "any") the user will be prompted with a system dialog to choose which type of authenticator they prefer. By providing one of the other options instead (e.g. "platform") you explicitly limit the authenticator types the user can choose from. On most devices this results in the most seamless WebAuthn user experience possible, as the system dialog will not be shown and the user will be prompted to authenticate directly.

Throws

slashid.errors_INTERNAL_ONLY.InvalidAuthenticationMethodError if the chosen method is incompatible with the given handle or is not available on the current device.

Fires

IdFlowSucceededEvent when the flow resolves successfully

Example

Authenticating a user is as simple as:

const user = await slashID.id({
  type: "phone_number",
  value: "+13337777777",
}, {
  method: "webauthn"
})

At this point the user has been authenticated; either registered or logged in.

You can use it in a header in your HTTP requests:

const response = await fetch(url, {
  ...
  headers: {
    'Authorization': `Bearer ${user.token}`,
     ...
  }
});

You can collect and associate user attributes:

const userDetails = { name: "...", streetAddress: "..." }
await user.set(userDetails)

You can perform multi-factor authentication before proceeding with your application logic:

await user.mfa({
  type: "email_address",
  value: "my.email@example.com"
}, {
  method: "email_link"
})

Parameters​

NameTypeDescription
oidstringYour organization ID.
handlePersonHandleHow the user wishes to identify, e.g. their e-mail address.
authenticationFactorFactorHow to verify the user's identity matches the handle.

Returns​

Promise<User>

The authenticated user.

isLocalScope​

▸ isLocalScope(rpID): boolean

Parameters​

NameType
rpIDstring

Returns​

boolean

publish​

▸ publish<Key>(type, event): void

Publish an event to the SDK. Currently available events are listed in PublicWriteEvents.

Type parameters​

NameType
Keyextends keyof PublicWriteEvents

Parameters​

NameType
typeKey
eventPublicWriteEvents[Key]

Returns​

void

recover​

▸ recover(__namedParameters): Promise<void>

Use a verified handle and a factor to start the account recovery flow. The user will receive instructions on how to proceed using a delivery mechanism based on the given handle. After this method resolves, the user will be able to authenticate using the same handle and factor.

Parameters​

NameType
__namedParametersObject
__namedParameters.factorRecoverableFactor
__namedParameters.handleReachablePersonHandle

Returns​

Promise<void>

resolveHostedLoginFlow​

▸ resolveHostedLoginFlow(): Promise<undefined | User>

Resolves the previously started login flow with a redirect to the hosted login page. Call this method on the page where the hosted login page redirects to.

Returns​

Promise<undefined | User>

startHostedLoginFlow​

▸ startHostedLoginFlow(params): Promise<void>

Starts the login flow with a redirect to the hosted login page.

Parameters​

NameType
paramsLogInWithOAuthParams

Returns​

Promise<void>

subscribe​

▸ subscribe<Key>(type, handler): void

Subscribe to the events published by the SDK. Currently available events are listed in PublicReadEvents.

Type parameters​

NameType
Keyextends keyof PublicReadEvents

Parameters​

NameType
typeKey
handlerHandler<PublicReadEvents[Key]>

Returns​

void

unsubscribe​

▸ unsubscribe<Key>(type, handler): void

Unsubscribe from the SDK events. Currently available events are listed in PublicReadEvents.

Type parameters​

NameType
Keyextends keyof PublicReadEvents

Parameters​

NameType
typeKey
handlerHandler<PublicReadEvents[Key]>

Returns​

void

canGetPublicKeyCredentialsInIFrame​

▸ Static canGetPublicKeyCredentialsInIFrame(): Promise<boolean>

Returns​

Promise<boolean>