# addNewWebAuthnDevice URL: /sdk-core/addNewWebAuthnDevice.html client.addNewWebAuthnDevice( [accessToken](#freshAccessToken): string, // Optional arguments [friendlyName](#friendlyName): string ) ## About this command When authenticated, the user can add a new FIDO2 device. > - The WebAuthn feature must be enabled on your Purse Identity account. > ## Examples ```javascript client.addNewWebAuthnDevice('eyJ0eXAiOiJKV1QiL...', 'My Android phone') ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ##### friendlyName string The name of the FIDO2 device. Each device must have a unique name. Default to the platform of the browser. ## Response Type: `Promise[void]` --- # checkSession URL: /sdk-core/checkSession.html client.checkSession([auth](#authCheckSession): AuthOptions) ## About this command Check if an SSO session is active by checking the presence and validity of the Purse Identity `__Host-Session` session cookie. If a session is still valid, authenticate the current user silently and return an [Authentication Result object](../docs/models-auth-result.html). This object includes a new access token, refresh token, and ID token even if the previous ones were not expired yet. > If no valid session is present, an error object is returned with a `login_required` error key. ## Examples ```javascript client .checkSession({ nonce: 'abcd' }) // The nonce links the retrieved id token with the local session .then(authResult => { // Retrieve the access token }) .catch(err => console.error(err)) ``` ## Parameters ##### auth AuthOptions List of authentication options ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ## Response Type: `Promise` ### AuthResult object fields ##### accessToken `string` ##### expiresIn `number` ##### tokenType `string` This is always `Bearer`. ##### refreshToken `string` A refresh token is not present unless you are implementing the refresh token grant. This is only possible when the `offline_access` [scope](../docs/scope.html) is requested. ##### idToken `string` _Claims_ are pieces of information made about a particular subject. For example, ID tokens might contain a claim called `name` that makes the claim that the name of the user authenticating is "Nicole Dubois". ```json { "sub": "987654321", "name": "Nicole Dubois", ... } ``` ##### idTokenPayload `JSON` For a full list of claims, check out the [JWT Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims). ##### code `string` ##### state `string` ##### stepUpToken `string` ##### amr `string` For more on `amr` values, see [here](https://www.rfc-editor.org/rfc/rfc8176.html). ##### providerName `string` This is only relevant for SLO and is not included in the auth response for other flows. ##### providerAccessToken `string` This is only relevant for SLO and is not included in the auth response for other flows. * * * #### ID token payload The possible claims to assert about an authenticated user are outlined in the table below. ##### authType `string` ##### birthdate `string` ##### email `string` ##### emailVerified `boolean` ##### exp `number` ##### familyName `string` Also known as surname or last name. ##### givenName `string` Also known as first name. ##### gender `string` Currently allowed values are `female`, `male` and `other`. ##### iat `number` ##### iss `string` ##### cico `string` ##### locale `string` ##### name `string` ##### newUser `boolean` ##### sub `string` ##### aud `string` ##### picture `string` ##### profile `string` ##### updatedAt `string` ##### auth\_time `number` --- # checkUrlFragment URL: /sdk-core/checkUrlFragment.html client.checkUrlFragment( // Optional arguments [url](#url): string ) ## About this command Checks whether the URL contains a success (`AuthResult`) or failure (`ErrorResponse`) response. If a response is detected, the method returns `true` and emits the: - `authenticated` event when there is a successful authentication result. - `authentication_failure` event when there is an error response. ## Examples ```javascript const responseDetected = client.checkUrlFragment() if (responseDetected) { // The `authenticated` event is fired } else { // The `authentication_failure` event is fired } ``` ## Parameters ##### url string The URL fragment to which the user-agent is redirected by the server. Defaults to the location object’s URL. ## Response Type: `boolean` --- # deleteTrustedDevices URL: /sdk-core/deleteTrustedDevices.html client.deleteTrustedDevices({ [accessToken](#accessToken): string, // Optional [trustedDeviceId](#trustedDeviceId): string }) ## About this command Delete user’s trusted devices. If a trusted device’s ID is specified, the specific trusted device is removed. Otherwise, all trusted devices are removed. A trusted device is a device the user has a second factor authentication method attached to and has explicitly assigned as trusted. ## Examples ```javascript client.deleteTrustedDevices('eyJ0eXAiOiJKV1QiL...', 'li3ZK302ko0k43k...') ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API. ##### trustedDeviceId string The ID for a specific trusted device. ## Response Type: `Promise[void]` --- # exchangeAuthorizationCodeWithPkce URL: /sdk-core/exchangeAuthorizationCodeWithPkce.html client.exchangeAuthorizationCodeWithPkce({ [code](#code): string, [redirectUri](#redirectUri): string }) ## About this command Get an access token by providing an authorization code. Only available if PKCE is enabled or if the authorization code was retrieved from the [loginWithSocialProvider](loginWithSocialProvider.html) method. Passwordless flow PKCE expects the same client context to complete both steps of the exchange. This means that if a user starts the flow on one device and then tries to complete it on a different device (e.g., by switching from mobile to tablet), the exchange fails. > The [`redirectUri` parameter](#redirectUri) must be identical to the `redirectUri` used in [loginWithPassword](loginWithPassword.html) or [loginWithSocialProvider](loginWithSocialProvider.html) methods. If they differ, the request will fail with the [400 : `"error.redirectUri.invalid"`](../docs/errors.html#reachfive-errors) error. ## Examples ```javascript client .exchangeAuthorizationCodeWithPkce({ code: 'QVVUSE9SSVpBVElPTl9DT0RF', redirectUri: 'https://www.example.com/login/callback' }) .then(authResult => { // Retrieve the access token }) .catch(err => console.error(err)) ``` ## Parameters ##### code string The authorization code. ##### redirectUri string The URL the user will be redirected to after getting the access token. ## Response Type: `Promise` ### AuthResult object fields ##### accessToken `string` ##### expiresIn `number` ##### tokenType `string` This is always `Bearer`. ##### refreshToken `string` A refresh token is not present unless you are implementing the refresh token grant. This is only possible when the `offline_access` [scope](../docs/scope.html) is requested. ##### idToken `string` _Claims_ are pieces of information made about a particular subject. For example, ID tokens might contain a claim called `name` that makes the claim that the name of the user authenticating is "Nicole Dubois". ```json { "sub": "987654321", "name": "Nicole Dubois", ... } ``` ##### idTokenPayload `JSON` For a full list of claims, check out the [JWT Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims). ##### code `string` ##### state `string` ##### stepUpToken `string` ##### amr `string` For more on `amr` values, see [here](https://www.rfc-editor.org/rfc/rfc8176.html). ##### providerName `string` This is only relevant for SLO and is not included in the auth response for other flows. ##### providerAccessToken `string` This is only relevant for SLO and is not included in the auth response for other flows. * * * #### ID token payload The possible claims to assert about an authenticated user are outlined in the table below. ##### authType `string` ##### birthdate `string` ##### email `string` ##### emailVerified `boolean` ##### exp `number` ##### familyName `string` Also known as surname or last name. ##### givenName `string` Also known as first name. ##### gender `string` Currently allowed values are `female`, `male` and `other`. ##### iat `number` ##### iss `string` ##### cico `string` ##### locale `string` ##### name `string` ##### newUser `boolean` ##### sub `string` ##### aud `string` ##### picture `string` ##### profile `string` ##### updatedAt `string` ##### auth\_time `number` --- # getMfaStepUpToken URL: /sdk-core/getMfaStepUpToken.html client.getMfaStepUpToken({ [options](#auth): {AuthOptions}, [accessToken](#freshAccessToken): string, [action](#action): string }) ## About this command Retrieves the stepup token needed for the MFA flow. > The presence of an active session cookie is required. It is automatically retrieved by the function. ## Examples ```javascript client.getMfaStepUpToken({ options: { redirectUri: 'https://www.example.com/login/callback', responseType: 'code' }, accessToken: 'eyJ0eXAiOiJKV1QiL...', action: 'stepup' }) ``` ## Parameters ##### options AuthOptions List of authentication options ##### responseType string The desired OAuth2 grant type. Use `code` to request an authorization code (recommended), `id_token` to request an ID token, or `token` for a token set (implicit grant, discouraged). > Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. ##### redirectUri string The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified `state` string will also be included. This parameter is required with `code` response type and defaults to the current page with `token` response type. `redirectUri` is still required when setting `useWebMessage` to `true` despite there being no redirection involved. ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### prompt string Specify whether the flow should explicitly prompt the user for reauthentication or not. > This applies to the Login with session flow where a session cookie is provided. > In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. The defined values are: - `none`: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent. > If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. - `login`: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the `redirect_uri` or client-configured login URL (if no `redirect_uri` is specified). - `consent`: The flow should prompt for consent, otherwise an error must be returned to the client (`consent_required`). This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### popupMode boolean Whether or not to use popup mode. Defaults to `false`. > This mode is not recommended due to known bugs in Android or Firefox in iOS. This mode is not recommended due to known bugs in Android or Firefox in iOS. ##### useWebMessage boolean When set to `true`, the SDK will leverage the `web_message` response mode in order to avoid having to redirect the user-agent to obtain the authorization response. Defaults to `false`. If set to `true` and `responseType` is `code`, the authorization code will be automatically exchanged at the token endpoint along with any potential `code_verifier`. ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### providerScope string List of space-delimited, case-sensitive strings representing the requested scope at the social provider. Defaults to the scope configured for the given provider in your Purse Identity Console. > Only for login with social provider. Only for login with social provider. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### returnProviderToken boolean Boolean that specifies whether you should return the provider access token. Defaults to `false`. If set to `true`, you retrieve the provider and provider access token as part of the [authentication result](../docs/models-auth-result.html). Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. This mode is not recommended due to known bugs in Android or Firefox in iOS. Only for login with social provider. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ##### action string A string describing the action for the MFA flow. You can value this with whatever you like. It should match the value you describe in your [MFA templates](../docs/mfa-templates.html). We recommend using meaningful values like `login` or `transaction` to help better align with MFA email and SMS templates. ## Response Type: `Promise` ##### amr string The [Authentication Method Reference](https://datatracker.ietf.org/doc/html/rfc8176). values - `sms` ##### token string The stepup token needed for stepup authentication. ## Next step (MFA flow) The next step after the `getMfaStepUpToken` method in the MFA flow is: [startPasswordless](startPasswordless.html) > See the [dedicated MFA guide for more details](../docs/mfa.html). --- # getPasswordStrength URL: /sdk-core/getPasswordStrength.html client.getPasswordStrength( [clientId](#clientId): string, [password](#password): string ) ## About this command Check the strength of a user’s password. ## Examples ```javascript client .getPasswordStrength(clientId,password) .then(PasswordStrength => { // Display strength of password }) .catch(err => console.error(err)) ``` ## Parameters ##### password string The user’s password. ##### clientId string The Purse Identity [client ID](../docs/clients.html#retrieve-client-credentials). ## Response Type: `Promise` ### PasswordStrength ##### score integer An integer representing the strength of a password. `score` values - `0` : **very weak** risky password. (guesses < 10^3) - `1` : **weak** protection from throttled online attacks. (guesses < 10^6) - `2` : **average** protection from unthrottled online attacks. (guesses < 10^8) - `3` : **strong** moderate protection from offline slow-hash scenario. (guesses < 10^10) - `4` : **very strong** strong protection from offline slow-hash scenario. (guesses >= 10^10) --- # getSessionInfo URL: /sdk-core/getSessionInfo.html client.getSessionInfo() ## About this command Check the state of the current’s SSO session and return an SSO session object. ## Examples ```javascript client .getSessionInfo() .then(sessionInfo => { if (sessionInfo.isAuthenticated) { // Do something } else { // Do something else } }) .catch(err => console.error(err)) ``` ## Response Type: `Promise` ### SessionInfo ##### isAuthenticated boolean Whether the profile is authenticated. ##### name string The full name of the profile. ##### email string The email address with which the profile has logged-in. ##### lastLoginType string The type of the last authentication. ##### hasPassword boolean Whether the profile has used a password to logged-in. ##### socialProviders string\[\] List of the social providers used by the profile. --- # getSignupData URL: /sdk-core/getSignupData.html client.getSignupData([signupToken](#signupToken): string) ## About this command Get lite user information by using the token received by mail after a signup invitation. ## Examples ```javascript client .getSignupData('eyJ0eXAiOiJKV1QiL...') .then(openIdUser => { // Display the signup data }) .catch(err => console.error(err)) ``` ## Parameters ##### signupToken string The access token received in the signup invitation email. Only usable once. ## Response Type: `Promise` ### OpenIdUser ##### sub string The subject claim identifies the profile. ##### name string The full name of the profile. ##### givenName string The given name of the profile. ##### middleName string The middle name of the profile. ##### familyName string The family name of the profile. ##### nickname string The nickname of the profile. ##### preferredUsername string The shorthand name by which the user wishes to be referred to. ##### profile string The URL of one of the user’s profile pages (_usually a social provider’s page_). ##### picture string The URL of one of the user’s profile pictures. This URL refers to an image file (PNG, JPEG, or GIF image file). ##### website string The URL of the user’s web page or blog. ##### email string The primary email address of the profile. ##### emailVerified boolean True if the user’s e-mail address has been verified; otherwise false. ##### gender string The gender of the profile. Allowed values are `female`, `male` and `other`. ##### birthdate string The birthdate of the profile, represented as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) `YYYY-MM-DD` format. ##### zoneinfo string The string from zoneinfo time zone database representing the user’s time zone. ##### locale string The user’s language code in lowercase and country code in uppercase, separated by a dash. ##### phoneNumber string The user’s preferred telephone number. ##### phoneNumberVerified boolean `true` if the user’s phone number has been verified; otherwise `false`. ##### addresses ProfileAddress\[\] The list of the profile’s postal addresses ##### customFields Map The custom fields of the profile. ##### updatedAt string The time the profile’s information was last updated. --- # getUser URL: /sdk-core/getUser.html client.getUser({ [accessToken](#accessToken): string, // Optional arguments [fields](#fields): string }) ## About this command Retrieve the user profile. ## Examples ```javascript client .getUser({ accessToken: 'eyJ0eXAiOiJKV1QiL...', fields: 'id,givenName,familyName,email,birthdate' }) .then(profile => { // Display the profile }) .catch(err => console.error(err)) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API. ##### fields string The user fields to fetch in the response. Defaults to `id,name,email`. ## Response Type: `Promise` where `Profile` is a `Record` --- # Getting Started URL: /sdk-core/index.html ![identity core](https://img.shields.io/npm/v/@reachfive/identity-core.svg?color=green) This page guides you on getting started with Purse Identity’s Core SDK and includes the following sections: - [Install Purse Identity](#install-purse-identity) - [Test drive the Core SDK](#test-drive-the-core-sdk) Install with npm If you’re experienced with npm and feel comfortable jumping straight in, the latest release is available on [npm](https://cdn.jsdelivr.net/npm/@reachfive/identity-core@latest/umd/identity-core.min.js) using the command below. Otherwise, follow along with [Install Purse Identity](#install-purse-identity). ```none npm install @reachfive/identity-core ``` #### Browser compatibility The **Core SDK** is compatible with the latest versions of: - [Edge](https://www.microsoft.com/en-us/edge) - [Chrome](https://www.google.com/intl/en/chrome/) - [Firefox](https://www.mozilla.org/en-US/firefox/) - [Safari](https://www.apple.com/safari/) > Internet Explorer is no longer supported as of the **17 August, 2021**. It has been [deprecated by Microsoft](https://blogs.windows.com/windowsexperience/2021/05/19/the-future-of-internet-explorer-on-windows-10-is-in-microsoft-edge/). * * * ## Install Purse Identity To install the Purse Identity client, you need to obtain your Purse Identity domain as well as your **Client ID**. These are found on the Purse Identity Console. After that, you’ll just need to paste the code snippet from [Create Purse Identity Client](#create-purse-identity-client) into your application or directly in a webpage (CDN). There are two steps: - [Get Domain and Client ID](#get-domain-and-client-id) - [Create Purse Identity Client](#create-purse-identity-client) ### Get Domain and Client ID #### Prerequisites - You must have access to the Purse Identity Console. - You must have a Developer, Manager, or Administrator [role](../docs/roles.html). #### Instructions 1. Log in to your Purse Identity Console. 2. Go to **Settings**. 3. Copy your Purse Identity [domain](../docs/console.html#get-domain). ![get domain](../docs/_images/get-domain.png) 4. Go to **Settings**  **Clients**. 5. Create a **New Client** or select an existing [client](../docs/clients.html). 6. Copy the desired **Client Id** you wish to use in your application. > Make sure to keep this handy when you [create the Purse Identity client](#create-purse-identity-client). 7. Under **Allowed Origins (CORS)**, add all URLs that will use the Purse Identity Core SDK. ![clients clientId CORS](../docs/_images/console/clients-clientId-CORS.png) ### Create Purse Identity Client You can use Node or the CDN to create a Purse Identity client. #### CDN vs Node You can choose to call Purse Identity’s SDK libraries with either Node or a Content Delivery Network (CDN). ##### CDN Using the CDN approach allows you to make the calls directly in a page without the need for Node or server-side code. ##### Node Using the Node approach means you want to make the libraries available to your entire ecosystem. > This is typically because you want to integrate it as part of your own SDK. **Prerequisites:** You must have [Node](https://nodejs.org/en/) installed in order to use the Node approach and install npm packages. You can also install npm packages with [yarn](https://yarnpkg.com/) if so desired. This is typically because you want to integrate it as part of your own SDK. 1. Install the latest release of Purse Identity from [npm](https://cdn.jsdelivr.net/npm/@reachfive/identity-core@latest/umd/identity-core.min.js) using the following command: ```none npm install @reachfive/identity-core ``` 2. Copy the following code snippet into your application. _See the [descriptions](#sdk-core-instantiate-descriptions-node) below for more details._ ```js import { createClient } from '@reachfive/identity-core'; (1) const DOMAIN = 'YOUR_PURSE_IDENTITY_DOMAIN'; (2) const CLIENT_ID = 'YOUR_PURSE_IDENTITY_CLIENT_ID'; (2) const client = createClient({ (3) // Required parameters domain: DOMAIN, (2) clientId: CLIENT_ID, (2) // Optional parameters language: 'Here paste a language code', (4) locale: 'fr-FR', (5) webAuthnOrigin: 'https://example.com' (6) }); ``` - (1) Import the `createClient` method from the `@reachfive/identity-core` npm package. - (2) Use your `DOMAIN` and `CLIENT_ID` that you got from the [Purse Identity Console](#get-domain-and-client-id). - (3) Use the `createClient` method to initialize a Purse Identity client. - (4) If you want to provide a language, paste the language code. _This will override the language detected in the browser by Purse Identity via the user’s locale._ See [supported languages](../docs/global-consumers/languages.html). - (5) Optional parameter where `fr-FR` is the locale and the value is automatically added in the `Custom-Locale` header parameter. - (6) Optional. Pass the **full origin URL** that must match an Allowed origin in **Settings**  **WebAuthn** (for example `https://example.com`). The Relying Party ID is the hostname of that URL (`example.com`). If omitted, the SDK uses `window.location.origin`. See [WebAuthn and passkey allowed origins](../docs/biometrics/passkeys.html#webauthn-and-passkey-allowed-origins) for dual-origin setups. Copy the following code snippet into your application. _See the [descriptions](#sdk-core-instantiate-descriptions-cdn) below for more details._ ```js const DOMAIN = 'YOUR_PURSE_IDENTITY_DOMAIN'; (1) const CLIENT_ID = 'YOUR_PURSE_IDENTITY_CLIENT_ID'; (1) (2) const client = reach5.createClient({ (3) // Required parameters domain: DOMAIN, clientId: CLIENT_ID, // Optional parameters language: 'Paste language code here', (4) locale: 'fr-FR', (5) webAuthnOrigin: 'https://example.com' (6) }); ``` - (1) Use your `DOMAIN` and `CLIENT_ID` that you got from the [Purse Identity Console](#get-domain-and-client-id). - (2) Replace `x.y.z` with the version you require or simply use `@latest` for the latest version. - (3) Use the `createClient` method on the `reach5` global variable to initialize a Purse Identity client. - (4) If you want to provide a language, paste the language code. _This will override the language detected in the browser by Purse Identity via the user’s locale._ Currently supported languages - `ar` - العربية _Arabic_ - `de` - Deutsch _German_ - `en` - English - `es` - Español _Spanish_ - `fr` - Français _French_ - `hu` - Magyar _Hungarian_ - `it` - Italiano _Italian_ - `jp` - 日本 _Japanese_ - `ko` - 한국인 _Korean_ - `nl` - Nederlands _Dutch_ - `pt` - Portuguese - `ru` - Ру́сский _Russian_ - `sk` - Slovenský _Slovak_ - `zh-CN` - _People’s Republic of China Simplified Chinese_ - `zh-Hans` - _Simplified Chinese_ - `zh-Hant` - _Traditional Chinese_ - `zh-HK` - _Hong Kong Traditional Chinese_ - `zh-MO` - _Macao Traditional Chinese_ - `zh-SG` - _Singapore Simplified Chinese_ - `zh-TW` - _Taiwan Traditional Chinese_ - (5) Optional parameter where `fr-FR` is the locale and the value is automatically added in the `Custom-Locale` header parameter. - (6) Optional. Pass the **full origin URL** that must match an Allowed origin in **Settings**  **WebAuthn** (for example `https://example.com`). The Relying Party ID is the hostname of that URL (`example.com`). If omitted, the SDK uses `window.location.origin`. See [WebAuthn and passkey allowed origins](../docs/biometrics/passkeys.html#webauthn-and-passkey-allowed-origins) for dual-origin setups. ## Test drive the Core SDK So you have successfully installed Purse Identity and you want to test it out before dropping it into your application. In this brief tutorial, we test out the Purse Identity client to make sure all is functioning properly. We will create a _very_ simple application that leverages your recently-installed Purse Identity client so you can see it in action. See the [video below](#test-drive-video) for a sneak peek at your _super simple test-drive_ in action. ### Prerequisites - You must have access to the Purse Identity Console. - You must have a Developer, Manager, or Administrator [role](../docs/roles.html). - You must have a code editor or IDE such as [Visual Studio Code](https://code.visualstudio.com/) or [IntelliJ](https://www.jetbrains.com/idea/). - You must have [npm](https://www.npmjs.com/) installed. - You must have installed the Purse Identity `@reachfive/identity-core` npm package. > If you haven’t, download it now: > > ```none > npm install @reachfive/identity-core > ``` ### Instructions 1. Create a folder called `test-drive` in your desired location. 2. Create a new file called `package.json` in your `test-drive` folder and copy the following into that file: ```json { "name": "test-drive", "version": "1.0.0", "description": "test-drive", "main": "index.js", "scripts": { "start": "parcel index.html", "test": "echo \"Error: no test specified\" && exit 1" }, "author": "", "license": "ISC", "dependencies": { "@reachfive/identity-core": "^1.20.1", "parcel-bundler": "^1.12.5" } } ``` 3. From the root of your `test-drive` folder, run: ```sh npm install ``` > This installs the dependencies listed in the `package.json` file. 4. Create a new file called `index.html` in your `test-drive` folder and copy the following into that file: ```html Test Drive ReachFive (1)

My Super Simple ReachFive Sandbox

(2)
(3)
We'll never share your email with anyone else.
(3)
@ (3)
``` - (1) Calls the `core.js` file that you will create in the next step. - (2) The `signup` method is trigged on the `onsubmit` event. - (3) The form fields. 5. Create a new filed called `core.js` in your `test-drive` folder and copy the following into that file: ```js import { createClient } from '@reachfive/identity-core' (1) const DOMAIN = 'YOUR_PURSE_IDENTITY_DOMAIN' (2) const CLIENT_ID = 'YOUR_PURSE_IDENTITY_CLIENT_ID' (3) const client = createClient({ (4) domain: DOMAIN, clientId: CLIENT_ID }) function signup(e) { e.preventDefault(); var form = document.getElementById('signup-form') var formData = new FormData(form) client.signup({ (5) data: { (6) email: formData.get('email'), password: formData.get('password'), givenName: formData.get('givenName') }, auth: { (7) redirectUri: 'http://localhost:1234' } }) .then(() => { (8) console.log("Signup") client.on('authenticated', authResult => { console.log("Listening 1") console.log("authResult1", authResult) }) }) .catch(console.log) return } window.signup = signup ``` - (1) Imports the Purse Identity client. - (2) Your Purse Identity `domain`. - (3) Your Purse Identity `client_id`. - (4) The client variable (which contains your `domain` and `client_id`). - (5) Calls the [signup](signup.html) method. - (6) Sets the [sign up data](signup.html#data) for the sign up form; in this case, `email`, `password`, and `name`. - (7) Uses the [auth options](signup.html#auth); in this case, sets the `redirectUri` to `[http://localhost:1234](http://localhost:1234)`. - (8) The **response** for the `signup` method. Here, we simply log to the console. Typically, you would receive token information. > See [the `authResult` object](signup.html#authresult-object-fields) for more details. 6. From the root of your `test-drive` folder, run: ```sh npm run start ``` 7. Open your browser to [`localhost:1234`](http://localhost:1234/). 8. Sign up a new user. Your browser does not support the video tag. 9. Go to your Purse Identity Console. 10. Navigate to **Analytics**  **Profiles** to see your newly-created user. Your browser does not support the video tag. Hooray! You have officially taken Purse Identity for a test drive. Now, go put it into action. Check out all of the methods for the Core SDK, available on the sidebar to your left. --- # instantiateOneTap URL: /sdk-core/instantiateOneTap.html client.instantiateOneTap{( [auth](#auth): AuthOptions )} ## About this command The `instantiateOneTap` method loads the necessary Google scripts and instantiates the widget for Google One Tap on your site. > The widget is loaded without checking on authentication from Purse Identity, so to avoid displaying the widget to authenticated users, it’s best to doing a [checkSession](checkSession.html) first as part of the implementation. ## Examples ```javascript client .instantiateOneTap({ scope: 'openid profile phone full_write', redirectUri: 'https://www.example.com/login/callback' }) ``` ## Parameters ##### options AuthOptions List of authentication options ##### responseType string The desired OAuth2 grant type. Use `code` to request an authorization code (recommended), `id_token` to request an ID token, or `token` for a token set (implicit grant, discouraged). > Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. ##### redirectUri string The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified `state` string will also be included. This parameter is required with `code` response type and defaults to the current page with `token` response type. `redirectUri` is still required when setting `useWebMessage` to `true` despite there being no redirection involved. ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### prompt string Specify whether the flow should explicitly prompt the user for reauthentication or not. > This applies to the Login with session flow where a session cookie is provided. > In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. The defined values are: - `none`: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent. > If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. - `login`: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the `redirect_uri` or client-configured login URL (if no `redirect_uri` is specified). - `consent`: The flow should prompt for consent, otherwise an error must be returned to the client (`consent_required`). This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### popupMode boolean Whether or not to use popup mode. Defaults to `false`. > This mode is not recommended due to known bugs in Android or Firefox in iOS. This mode is not recommended due to known bugs in Android or Firefox in iOS. ##### useWebMessage boolean When set to `true`, the SDK will leverage the `web_message` response mode in order to avoid having to redirect the user-agent to obtain the authorization response. Defaults to `false`. If set to `true` and `responseType` is `code`, the authorization code will be automatically exchanged at the token endpoint along with any potential `code_verifier`. ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### accessToken string Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old). ##### providerScope string List of space-delimited, case-sensitive strings representing the requested scope at the social provider. Defaults to the scope configured for the given provider in your Purse Identity Console. > Only for login with social provider. Only for login with social provider. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### returnProviderToken boolean Boolean that specifies whether you should return the provider access token. Defaults to `false`. If set to `true`, you retrieve the provider and provider access token as part of the [authentication result](../docs/models-auth-result.html). Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. This mode is not recommended due to known bugs in Android or Firefox in iOS. Only for login with social provider. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ## Response Type: `Promise[void]` --- # listMfaCredentials URL: /sdk-core/listMfaCredentials.html client.listMfaCredentials([accessToken](#freshAccessToken): string) ## About this command Lists the user’s MFA credentials. > This is typically the phone number registered to use with MFA. ## Examples ```javascript client.listMfaCredentials('eyJ0eXAiOiJKV1QiL...') ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ## Response Type: `Promise` ##### credentials array An array of objects, each containing information on a specific credential. ##### type CredentialType Specifies the type of credential. Values: `sms`. ##### createdAt string The date on which the credential was created. Format `"YYYY-MM-DD"` ##### friendlyName string The user-friendly name for the credential. ##### phone\_number string The user’s phone number. Example ```json { credentials: [{ type: "sms", createdAt: "2026-10-30" }] } ``` ## Next step (MFA flow) The next step after the `listMfaCredentials` method in the MFA flow is: [getMfaStepUpToken](getMfaStepUpToken.html) > See the [dedicated MFA guide for more details](../docs/mfa.html). --- # listSessionDevices URL: /sdk-core/listSessionDevices.html client.listSessionDevices([accessToken](#accessToken): string) ## About this command Lists the active session devices for the authenticated user. > The access token must include the `session` scope. If the user is enrolled in [MFA](../docs/mfa.html), the token must also include the `amr:mfa` claim. ## Examples ```javascript client.listSessionDevices('eyJ0eXAiOiJKV1QiL...') ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API. ## Response Type: `Promise` ```none SessionDevice[]: SessionDevice[] (1) ``` - (1) An array of `SessionDevice` objects. Where each `SessionDevice` contains the fields below. ##### id The unique identifier for the session device. ##### tokenType The type of authentication token associated with this device session. Values are `RT` (refresh token) or `ST` (short-lived token). ##### ip The IP address from which the device connected or established the session. ##### country The country resolved from the device IP address at login time. ##### city The city resolved from the device IP address at login time. ##### operatingSystem The operating system running on the device. ##### userAgentName The browser or client user agent name. ##### deviceClass The classification category of the device (for example, `Desktop`, `Mobile`, or `Tablet`). ##### deviceName The user-friendly or system-assigned name of the device. ##### createdAt The timestamp when the device session was initially created. ##### lastConnection The timestamp of the device’s most recent activity or network connection. ##### expiresAt The timestamp when the device session is scheduled to expire. Example ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "tokenType": "RT", "ip": "192.168.1.15", "country": "France", "city": "Asnières-sur-Seine", "operatingSystem": "iOS 17.4", "userAgentName": "Mobile Safari", "deviceClass": "SmartPhone", "deviceName": "iPhone 15 Pro", "createdAt": "2026-10-30", "lastConnection": "2026-10-30", "expiresAt": "2026-10-30" } ] ``` --- # listTrustedDevices URL: /sdk-core/listTrustedDevices.html client.listTrustedDevices({ [accessToken](#accessToken): string }) ## About this command Lists user’s trusted devices. A trusted device is a device the user has a second factor authentication method attached to and has explicitly assigned as trusted. ## Examples ```javascript client.listTrustedDevices('eyJ0eXAiOiJKV1QiL...') ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API. ## Response Type: `Promise` ```none ListTrustedDevicesResponse: { trustedDevices: TrustedDevice[] (1) } ``` - (1) Where the information for a `TrustedDevice` is shown below. ##### id The ID of the trusted device. ##### metadata Metadata object associated with the trusted device. This includes: - `ip`: The IP of the trusted device. - `operatingSystemAgent`: The Operating System such as Windows 11. - `userAgent`: The User Agent information such as `Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion`. - `deviceClass`: The device class such as mobile. - `deviceName`: The device name such as "My Mobile". ##### userId The ID of the user. ##### createdAt The time at which the trusted device entry was created. --- # listWebAuthnDevices URL: /sdk-core/listWebAuthnDevices.html client.listWebAuthnDevices([accessToken](#freshAccessToken): string) ## About this command When authenticated, the user can list the registred FIDO2 devices. > - The WebAuthn feature must be enabled on your Purse Identity account. > ## Examples ```javascript client .listWebAuthnDevices('eyJ0eXAiOiJKV1QiL...') .then(deviceCredentials => { // Display the list of device credentials }) .catch(err => console.error(err)) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ## Response Type: `Promise` ### DeviceCredential ##### friendlyName string The name of the FIDO2 device. ##### id string The identifier of the FIDO2 device. ##### createdAt string The date and time when the passkey was created. ##### lastUsedAt string The date and time when the passkey was last used. ##### aaguid string The Authenticator Attestation Globally Unique Identifier, a unique number that identifies the model of the authenticator. > This isn’t always present in the response. This isn’t always present in the response. --- # loginFromSession URL: /sdk-core/loginFromSession.html client.loginFromSession([auth](#auth): AuthOptions) ## About this command Authenticate the user from the current SSO session. ## Examples ```javascript client.loginFromSession({ redirectUri: 'https://www.example.com/login/callback' }) ``` ## Parameters ##### options AuthOptions List of authentication options ##### responseType string The desired OAuth2 grant type. Use `code` to request an authorization code (recommended), `id_token` to request an ID token, or `token` for a token set (implicit grant, discouraged). > Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. ##### redirectUri string The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified `state` string will also be included. This parameter is required with `code` response type and defaults to the current page with `token` response type. ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### prompt string Specify whether the flow should explicitly prompt the user for reauthentication or not. > This applies to the Login with session flow where a session cookie is provided. > In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. The defined values are: - `none`: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent. > If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. - `login`: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the `redirect_uri` or client-configured login URL (if no `redirect_uri` is specified). - `consent`: The flow should prompt for consent, otherwise an error must be returned to the client (`consent_required`). This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### popupMode boolean Whether or not to use popup mode. Defaults to `false`. > This mode is not recommended due to known bugs in Android or Firefox in iOS. This mode is not recommended due to known bugs in Android or Firefox in iOS. ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### accessToken string Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old). ##### providerScope string List of space-delimited, case-sensitive strings representing the requested scope at the social provider. Defaults to the scope configured for the given provider in your Purse Identity Console. > Only for login with social provider. Only for login with social provider. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### returnProviderToken boolean Boolean that specifies whether you should return the provider access token. Defaults to `false`. If set to `true`, you retrieve the provider and provider access token as part of the [authentication result](../docs/models-auth-result.html). Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. This mode is not recommended due to known bugs in Android or Firefox in iOS. Only for login with social provider. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ## Response Type: `Promise[void]` --- # loginWithCredentials URL: /sdk-core/loginWithCredentials.html client.loginWithCrendentials({ // Optional arguments [mediation](#mediation): string, [auth](#auth): AuthOptions }) ## About this command Authenticate the user from stored credentials in the browser using the Credentials Management API. > This feature is experimental, please check your [browser compatibility](https://caniuse.com/#feat=credential-management). ## Examples ```javascript client .loginWithCredentials({ mediation: 'silent' }) .then(authResult => { // Retrieve the access token }) .catch(err => console.error(err)) ``` ## Parameters ##### mediation string The mediation type to request the credentials. Allowed values: `silent`, `optional` and `required`. ##### options AuthOptions List of authentication options ##### responseType string The desired OAuth2 grant type. Use `code` to request an authorization code (recommended), `id_token` to request an ID token, or `token` for a token set (implicit grant, discouraged). > Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. ##### redirectUri string The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified `state` string will also be included. This parameter is required with `code` response type and defaults to the current page with `token` response type. `redirectUri` is still required when setting `useWebMessage` to `true` despite there being no redirection involved. ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### prompt string Specify whether the flow should explicitly prompt the user for reauthentication or not. > This applies to the Login with session flow where a session cookie is provided. > In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. The defined values are: - `none`: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent. > If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. - `login`: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the `redirect_uri` or client-configured login URL (if no `redirect_uri` is specified). - `consent`: The flow should prompt for consent, otherwise an error must be returned to the client (`consent_required`). This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### popupMode boolean Whether or not to use popup mode. Defaults to `false`. > This mode is not recommended due to known bugs in Android or Firefox in iOS. This mode is not recommended due to known bugs in Android or Firefox in iOS. ##### useWebMessage boolean When set to `true`, the SDK will leverage the `web_message` response mode in order to avoid having to redirect the user-agent to obtain the authorization response. Defaults to `false`. If set to `true` and `responseType` is `code`, the authorization code will be automatically exchanged at the token endpoint along with any potential `code_verifier`. ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### accessToken string Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old). ##### providerScope string List of space-delimited, case-sensitive strings representing the requested scope at the social provider. Defaults to the scope configured for the given provider in your Purse Identity Console. > Only for login with social provider. Only for login with social provider. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### returnProviderToken boolean Boolean that specifies whether you should return the provider access token. Defaults to `false`. If set to `true`, you retrieve the provider and provider access token as part of the [authentication result](../docs/models-auth-result.html). Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. This mode is not recommended due to known bugs in Android or Firefox in iOS. Only for login with social provider. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ## Response Type: `Promise` ### AuthResult object fields ##### accessToken `string` ##### expiresIn `number` ##### tokenType `string` This is always `Bearer`. ##### refreshToken `string` A refresh token is not present unless you are implementing the refresh token grant. This is only possible when the `offline_access` [scope](../docs/scope.html) is requested. ##### idToken `string` _Claims_ are pieces of information made about a particular subject. For example, ID tokens might contain a claim called `name` that makes the claim that the name of the user authenticating is "Nicole Dubois". ```json { "sub": "987654321", "name": "Nicole Dubois", ... } ``` ##### idTokenPayload `JSON` For a full list of claims, check out the [JWT Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims). ##### code `string` ##### state `string` ##### stepUpToken `string` ##### amr `string` For more on `amr` values, see [here](https://www.rfc-editor.org/rfc/rfc8176.html). ##### providerName `string` This is only relevant for SLO and is not included in the auth response for other flows. ##### providerAccessToken `string` This is only relevant for SLO and is not included in the auth response for other flows. * * * #### ID token payload The possible claims to assert about an authenticated user are outlined in the table below. ##### authType `string` ##### birthdate `string` ##### email `string` ##### emailVerified `boolean` ##### exp `number` ##### familyName `string` Also known as surname or last name. ##### givenName `string` Also known as first name. ##### gender `string` Currently allowed values are `female`, `male` and `other`. ##### iat `number` ##### iss `string` ##### cico `string` ##### locale `string` ##### name `string` ##### newUser `boolean` ##### sub `string` ##### aud `string` ##### picture `string` ##### profile `string` ##### updatedAt `string` ##### auth\_time `number` --- # loginWithPassword URL: /sdk-core/loginWithPassword.html // Login with password and email client.loginWithPassword({ [email](#email): string, [password](#password): string, // Optional arguments [saveCredentials](#saveCredentials): boolean, [captchaToken](#captchaToken): string, [captchaProvider](#captchaProvider): string, [auth](#auth): AuthOptions, [action](#action): string **(1)** }) // Login with password and phone number client.loginWithPassword({ [phoneNumber](#phoneNumber): string, [password](#password): string, // Optional arguments [saveCredentials](#saveCredentials): boolean, [captchaToken](#captchaToken): string, [captchaProvider](#captchaProvider): string, [auth](#auth): AuthOptions, [action](#action): string **(1)** }) // Login with a custom identifier and email client.loginWithPassword({ [customIdentifier](#customIdentifier): string, [password](#password): string, // Optional arguments [saveCredentials](#saveCredentials): boolean, [captchaToken](#captchaToken): string, [captchaProvider](#captchaProvider): string, [auth](#auth): AuthOptions, [action](#action): string **(1)** }) - (1) Applies only if step up is required. ## About this command Authenticate the user with a password and the specified identifier (email or phone number). ## Examples ```javascript // Authentication with redirection client .loginWithPassword({ email: 'john.doe@example.com', password: 'N5uiKvve', captchaToken: '03AGdBq27OYjM-...-w2PcTTETbErfyzV42IE4TY4CJRQoU1Or3B', auth: { redirectUri: 'https://www.example.com/login/callback' } }) // Authentication with no redirection client .loginWithPassword({ email: 'john.doe@example.com', password: 'N5uiKvve', auth: { useWebMessage: true, redirectUri: 'https://www.example.com/login/callback' } }) .then(authResult => { // Retrieve the access token }) .catch(err => console.error(err)) ``` ```javascript // Authentication with redirection client .loginWithPassword({ phoneNumber: '+33606060606', password: 'N5uiKvve', auth: { redirectUri: 'https://www.example.com/login/callback' } }) // Authentication with no redirection client .loginWithPassword({ phoneNumber: '+33606060606', password: 'N5uiKvve', captchaToken: '03AGdBq27OYjM-...-w2PcTTETbErfyzV42IE4TY4CJRQoU1Or3B', auth: { useWebMessage: true, redirectUri: 'https://www.example.com/login/callback' } }) .then(authResult => { // Retrieve the access token }) .catch(err => console.error(err)) ``` ```javascript // Authentication with redirection client .loginWithPassword({ customIdentifier: 'rollingUser1', password: 'N5uiKvve', captchaToken: '03AGdBq27OYjM-...-w2PcTTETbErfyzV42IE4TY4CJRQoU1Or3B', auth: { redirectUri: 'https://www.example.com/login/callback' } }) // Authentication with no redirection client .loginWithPassword({ customIdentifier: 'rollingUser1', password: 'N5uiKvve', auth: { useWebMessage: true, redirectUri: 'https://www.example.com/login/callback' } }) .then(authResult => { // Retrieve the access token }) .catch(err => console.error(err)) ``` ## Parameters ##### email string The user’s email address. ##### phoneNumber string The user’s phone number. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. ##### customIdentifier string A string that allows users to authenticate with something other than an `email` or `phone_number`. It’s important to note that an `email` and/or `phone_number` is still required to create a managed profile. Each `custom_identifier` value must be unique. The `custom_identifier` must be between _4-80_ characters. ##### password string The user’s password. ##### saveCredentials boolean Store the user credentials with the Credentials Management API. Defaults to `false`. > This feature is experimental, please check your [browser compatibility](https://caniuse.com/#feat=credential-management). This feature is experimental, please check your [browser compatibility](https://caniuse.com/#feat=credential-management). ##### captchaToken string Pass along the response token you have received from the captcha provider. - For reCAPTCHA, see [Google’s documentation on how to obtain it](https://developers.google.com/recaptcha/docs/v3) - For CaptchaFox, see [CaptchaFox’s documentation on how to obtain it](https://docs.captchafox.com/) Defaults to `null`. ##### captchaProvider string The captcha provider. This is one of the following: - `recaptcha` - `captchafox` ##### options AuthOptions List of authentication options ##### responseType string The desired OAuth2 grant type. Use `code` to request an authorization code (recommended), `id_token` to request an ID token, or `token` for a token set (implicit grant, discouraged). > Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. ##### redirectUri string The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified `state` string will also be included. This parameter is required with `code` response type and defaults to the current page with `token` response type. `redirectUri` is still required when setting `useWebMessage` to `true` despite there being no redirection involved. ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### prompt string Specify whether the flow should explicitly prompt the user for reauthentication or not. > This applies to the Login with session flow where a session cookie is provided. > In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. The defined values are: - `none`: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent. > If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. - `login`: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the `redirect_uri` or client-configured login URL (if no `redirect_uri` is specified). - `consent`: The flow should prompt for consent, otherwise an error must be returned to the client (`consent_required`). This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### popupMode boolean Whether or not to use popup mode. Defaults to `false`. > This mode is not recommended due to known bugs in Android or Firefox in iOS. This mode is not recommended due to known bugs in Android or Firefox in iOS. ##### useWebMessage boolean When set to `true`, the SDK will leverage the `web_message` response mode in order to avoid having to redirect the user-agent to obtain the authorization response. Defaults to `false`. If set to `true` and `responseType` is `code`, the authorization code will be automatically exchanged at the token endpoint along with any potential `code_verifier`. ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### accessToken string Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old). ##### providerScope string List of space-delimited, case-sensitive strings representing the requested scope at the social provider. Defaults to the scope configured for the given provider in your Purse Identity Console. > Only for login with social provider. Only for login with social provider. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### returnProviderToken boolean Boolean that specifies whether you should return the provider access token. Defaults to `false`. If set to `true`, you retrieve the provider and provider access token as part of the [authentication result](../docs/models-auth-result.html). Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. This mode is not recommended due to known bugs in Android or Firefox in iOS. Only for login with social provider. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### action string A string describing the action for the MFA flow. You can value this with whatever you like. It should match the value you describe in your [MFA templates](../docs/mfa-templates.html). We recommend using meaningful values like `login` or `transaction` to help better align with MFA email and SMS templates. ## Response Type: `Promise` ### AuthResult object fields ##### accessToken `string` ##### expiresIn `number` ##### tokenType `string` This is always `Bearer`. ##### refreshToken `string` A refresh token is not present unless you are implementing the refresh token grant. This is only possible when the `offline_access` [scope](../docs/scope.html) is requested. ##### idToken `string` _Claims_ are pieces of information made about a particular subject. For example, ID tokens might contain a claim called `name` that makes the claim that the name of the user authenticating is "Nicole Dubois". ```json { "sub": "987654321", "name": "Nicole Dubois", ... } ``` ##### idTokenPayload `JSON` For a full list of claims, check out the [JWT Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims). ##### code `string` ##### state `string` ##### stepUpToken `string` ##### amr `string` For more on `amr` values, see [here](https://www.rfc-editor.org/rfc/rfc8176.html). ##### providerName `string` This is only relevant for SLO and is not included in the auth response for other flows. ##### providerAccessToken `string` This is only relevant for SLO and is not included in the auth response for other flows. * * * #### ID token payload The possible claims to assert about an authenticated user are outlined in the table below. ##### authType `string` ##### birthdate `string` ##### email `string` ##### emailVerified `boolean` ##### exp `number` ##### familyName `string` Also known as surname or last name. ##### givenName `string` Also known as first name. ##### gender `string` Currently allowed values are `female`, `male` and `other`. ##### iat `number` ##### iss `string` ##### cico `string` ##### locale `string` ##### name `string` ##### newUser `boolean` ##### sub `string` ##### aud `string` ##### picture `string` ##### profile `string` ##### updatedAt `string` ##### auth\_time `number` --- # loginWithSocialProvider URL: /sdk-core/loginWithSocialProvider.html client.loginWithSocialProvider({ [provider](#provider): string, [auth](#auth): AuthOptions **(1)** }) - (1) With some social providers, you can retrieve information such as the provider access token. ## About this command Authenticate the user with the specified social provider. > For the Cordova platform: > > - The system’s web browser will be used for Android. > > - A webview will be opened in the application for iOS. > ## Examples ```javascript client.loginWithSocialProvider('facebook', { redirectUri: 'https://www.example.com/login/callback' }) ``` ## Parameters ##### provider string The name of the provider to use (for instance: `facebook`, `google` …). You can also configure variants for a provider as a key:value pair: ```none : (1) ``` - (1) Where `provider` is the provider like `line` and the variant is the specific version of that provider like `korea`. **Example** `line:korea`. ##### 1 Where `provider` is the provider like `line` and the variant is the specific version of that provider like `korea`. **Example** `line:korea`. ##### options AuthOptions List of authentication options ##### responseType string The desired OAuth2 grant type. Use `code` to request an authorization code (recommended), `id_token` to request an ID token, or `token` for a token set (implicit grant, discouraged). > Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. ##### redirectUri string The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified `state` string will also be included. This parameter is required with `code` response type and defaults to the current page with `token` response type. `redirectUri` is still required when setting `useWebMessage` to `true` despite there being no redirection involved. ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### prompt string Specify whether the flow should explicitly prompt the user for reauthentication or not. > This applies to the Login with session flow where a session cookie is provided. > In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. The defined values are: - `none`: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent. > If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. - `login`: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the `redirect_uri` or client-configured login URL (if no `redirect_uri` is specified). - `consent`: The flow should prompt for consent, otherwise an error must be returned to the client (`consent_required`). This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### popupMode boolean Whether or not to use popup mode. Defaults to `false`. > This mode is not recommended due to known bugs in Android or Firefox in iOS. This mode is not recommended due to known bugs in Android or Firefox in iOS. ##### useWebMessage boolean When set to `true`, the SDK will leverage the `web_message` response mode in order to avoid having to redirect the user-agent to obtain the authorization response. Defaults to `false`. If set to `true` and `responseType` is `code`, the authorization code will be automatically exchanged at the token endpoint along with any potential `code_verifier`. ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### accessToken string Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old). ##### providerScope string List of space-delimited, case-sensitive strings representing the requested scope at the social provider. Defaults to the scope configured for the given provider in your Purse Identity Console. > Only for login with social provider. Only for login with social provider. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### returnProviderToken boolean Boolean that specifies whether you should return the provider access token. Defaults to `false`. If set to `true`, you retrieve the provider and provider access token as part of the [authentication result](../docs/models-auth-result.html). Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. This mode is not recommended due to known bugs in Android or Firefox in iOS. Only for login with social provider. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ## Response Type: `Promise[void | InAppBrowser]` --- # loginWithWebAuthn URL: /sdk-core/loginWithWebAuthn.html // Login with WebAuthn and email client.loginWithWebAuthn({ [email](#email): string, // Optional arguments [auth](#auth): AuthOptions }) // Login with WebAuthn and phone number client.loginWithWebAuthn({ [phoneNumber](#phoneNumber): string, // Optional arguments [auth](#auth): AuthOptions }) // Discoverable (identifier-less) login client.loginWithWebAuthn({ [conditionalMediation](#conditionalMediation): boolean | `'preferred'`, // Optional arguments [signal](#signal): AbortSignal, [auth](#auth): AuthOptions }) ## About this command A user with an already registered credential visits Purse Identity’s login page to authenticate using the FIDO2 public-key based credential. Pass `email` or `phoneNumber` for a non-discoverable login, where the user supplies an identifier before the passkey ceremony. Pass `conditionalMediation` (with no identifier) for a discoverable login, where the authenticator or keychain supplies both the identifier and the passkey. > - The WebAuthn feature must be enabled on your Purse Identity account. > > - The SMS feature must be enabled on your Purse Identity account if the profile can choose a phone number to login. > > - Discoverable (identifier-less) login is available from Core JS SDK `1.32.2`. > ## Examples ```javascript client .loginWithWebAuthn({ email: 'john.doe@example.com', auth: { redirectUri: 'https://www.example.com/login/callback', scope: 'openid profile email full_write' } }) .then(authResult => { // Retrieve the access token }) .catch(err => console.error(err)) ``` ```javascript client .loginWithWebAuthn({ phoneNumber: '+33682234940', auth: { scope: 'openid profile phone full_write' } }) .then(authResult => { // Retrieve the access token }) .catch(err => console.error(err)) ``` ```javascript const controller = new AbortController() client .loginWithWebAuthn({ conditionalMediation: 'preferred', signal: controller.signal, auth: { redirectUri: 'https://www.example.com/login/callback', scope: 'openid profile email full_write' } }) .then(authResult => { // Retrieve the access token }) .catch(err => console.error(err)) ``` ## Parameters ##### email string The user’s email address. ##### phoneNumber string The user’s phone number. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. ##### conditionalMediation boolean or 'preferred' Selects discoverable (identifier-less) passkey login and controls whether to use conditional mediation (browser autofill) or a modal request. Allowed values: - `true`: Use conditional mediation. The call fails with an error if the browser does not support it. - `false`: Use a modal request. - `'preferred'`: Use conditional mediation when the browser supports it, otherwise fall back to a modal request. Do not pass `email` or `phoneNumber` with this parameter. The identifier is provided by the authenticator or keychain. See [Discoverable and Non-discoverable logins](../docs/biometrics/passkeys.html#discoverable-and-non-discoverable-logins) for more on this flow. ##### signal AbortSignal Optional `AbortSignal` used to cancel the WebAuthn ceremony. This is most useful with discoverable login and conditional mediation, because browsers typically allow only one `navigator.credentials.get()` request at a time. Abort the pending autofill request before starting another credentials request (for example a modal passkey login or a password login). ##### options AuthOptions List of authentication options ##### responseType string The desired OAuth2 grant type. Use `code` to request an authorization code (recommended), `id_token` to request an ID token, or `token` for a token set (implicit grant, discouraged). > Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. ##### redirectUri string The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified `state` string will also be included. This parameter is required with `code` response type and defaults to the current page with `token` response type. `redirectUri` is still required when setting `useWebMessage` to `true` despite there being no redirection involved. ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### prompt string Specify whether the flow should explicitly prompt the user for reauthentication or not. > This applies to the Login with session flow where a session cookie is provided. > In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. The defined values are: - `none`: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent. > If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. - `login`: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the `redirect_uri` or client-configured login URL (if no `redirect_uri` is specified). - `consent`: The flow should prompt for consent, otherwise an error must be returned to the client (`consent_required`). This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### popupMode boolean Whether or not to use popup mode. Defaults to `false`. > This mode is not recommended due to known bugs in Android or Firefox in iOS. This mode is not recommended due to known bugs in Android or Firefox in iOS. ##### useWebMessage boolean When set to `true`, the SDK will leverage the `web_message` response mode in order to avoid having to redirect the user-agent to obtain the authorization response. Defaults to `false`. If set to `true` and `responseType` is `code`, the authorization code will be automatically exchanged at the token endpoint along with any potential `code_verifier`. ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### accessToken string Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old). ##### providerScope string List of space-delimited, case-sensitive strings representing the requested scope at the social provider. Defaults to the scope configured for the given provider in your Purse Identity Console. > Only for login with social provider. Only for login with social provider. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### returnProviderToken boolean Boolean that specifies whether you should return the provider access token. Defaults to `false`. If set to `true`, you retrieve the provider and provider access token as part of the [authentication result](../docs/models-auth-result.html). Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. This mode is not recommended due to known bugs in Android or Firefox in iOS. Only for login with social provider. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ## Response Type: `Promise` ### AuthResult object fields ##### accessToken `string` ##### expiresIn `number` ##### tokenType `string` This is always `Bearer`. ##### refreshToken `string` A refresh token is not present unless you are implementing the refresh token grant. This is only possible when the `offline_access` [scope](../docs/scope.html) is requested. ##### idToken `string` _Claims_ are pieces of information made about a particular subject. For example, ID tokens might contain a claim called `name` that makes the claim that the name of the user authenticating is "Nicole Dubois". ```json { "sub": "987654321", "name": "Nicole Dubois", ... } ``` ##### idTokenPayload `JSON` For a full list of claims, check out the [JWT Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims). ##### code `string` ##### state `string` ##### stepUpToken `string` ##### amr `string` For more on `amr` values, see [here](https://www.rfc-editor.org/rfc/rfc8176.html). ##### providerName `string` This is only relevant for SLO and is not included in the auth response for other flows. ##### providerAccessToken `string` This is only relevant for SLO and is not included in the auth response for other flows. * * * #### ID token payload The possible claims to assert about an authenticated user are outlined in the table below. ##### authType `string` ##### birthdate `string` ##### email `string` ##### emailVerified `boolean` ##### exp `number` ##### familyName `string` Also known as surname or last name. ##### givenName `string` Also known as first name. ##### gender `string` Currently allowed values are `female`, `male` and `other`. ##### iat `number` ##### iss `string` ##### cico `string` ##### locale `string` ##### name `string` ##### newUser `boolean` ##### sub `string` ##### aud `string` ##### picture `string` ##### profile `string` ##### updatedAt `string` ##### auth\_time `number` --- # logout URL: /sdk-core/logout.html client.logout({ [redirectTo](#redirectTo): string, [removeCredentials](#removeCredentials): boolean, // optional arguments [state](#state): string, [revocationParams](#revocationParams): string\[\] }) ## About this command Kill the current user’s SSO session. > Use the [Revoke refresh token](https://docs.identity.purse.eu/openapi/identity.html#operation/revokeToken) endpoint to invalidate all active user tokens on a specific `client_id`. ## Examples ```javascript client.logout({ redirectTo: 'https://my-site.com/logout', state: 'L2ZyL3BhZ2U=', revocationParams: ['eyJ..V1QiL'] }) ``` ## Parameters ##### redirectTo string The URL to which the user is redirected afterward. This URL must be whitelisted in the `Allowed logout callback URLs` field of your Purse Identity Console SSO settings (**Security**  **SSO**). Whitelisted URLs can be used with all account identity clients. ##### state string **Optional.** An opaque value that Purse Identity returns as-is as the `state` query parameter on the post-logout redirect URL. The recommended format for `state` is Base64. Use `state` to encode the original page (for example, path and language) so you only need to whitelist one logout callback URL. Your application then decodes `state` and performs the final redirect to that page. If no redirect occurs, `state` is ignored. ##### revocationParams string An array of strings that is used to pass any access or refresh tokens that should be invalidated after a logout. > This parameter can only be used with an OAuth2 [public client](https://tools.ietf.org/html/rfc6749#section-2.1). This parameter can only be used with an OAuth2 [public client](https://tools.ietf.org/html/rfc6749#section-2.1). ##### removeCredentials boolean Delete the user credentials with the Credentials Management API. See [loginWithCredentials](loginWithCredentials.html) for more on logging in with credentials. Defaults to `false`. > This feature is experimental, please check your [browser compatibility](https://caniuse.com/#feat=credential-management). This feature is experimental, please check your [browser compatibility](https://caniuse.com/#feat=credential-management). ## Response Type: `Promise[void]` --- # off URL: /sdk-core/off.html client.off([eventName](#eventName): Event, [callback](#callback): function) ## About this command Removes a previously registered listener for a particular Purse Identity event. ## Examples ```javascript function onAuthenticated(authResult) { const accessToken = authResult.accessToken // ... } client.on('authenticated', onAuthenticated) // Then later client.off('authenticated', onAuthenticated) ``` ## Parameters ##### eventName Event One of the following events: - `authenticated`: emitted after a successful authentication. - `authentication_failed`: emitted after a failed authentication with a social provider. - `login_failed`: emitted after a failed password or Webauthn login. - `signup_failed`: emitted after a failed signup. - `profile_updated`: emitted after a successful profile update. - `ready`: emitted when the SDK is fully loaded. If the SDK is already loaded, the handler is called synchronously. ##### callback function The function called when the event was registered. ## Response Type: `void` --- # on URL: /sdk-core/on.html client.on([eventName](#eventName): Event, [callback](#callback): function) ## About this command Add a listener for a particular Purse Identity event. ## Examples ```javascript client.on('authenticated', authResult => { const accessToken = authResult.accessToken // ... }) ``` ## Parameters ##### eventName Event One of the following events: - `authenticated`: emitted after a successful authentication. - `authentication_failed`: emitted after a failed authentication with a social provider. - `login_failed`: emitted after a failed password or Webauthn login. - `signup_failed`: emitted after a failed signup. - `profile_updated`: emitted after a successful profile update. - `ready`: emitted when the SDK is fully loaded. If the SDK is already loaded, the handler is called synchronously. ##### callback function The function called when the event occurs. ## Response Type: `void` --- # refreshTokens URL: /sdk-core/refreshTokens.html client.refreshTokens({ [refreshToken](#parameters): string, [scope](#parameters): string }) ## About this command Implements the refresh token grant. This retrieves a new refresh and access token with the current refresh token. > Redeeming a new refresh token invalidates the consumed access/refresh token (AT/RT) pair. > Check out our [Refresh tokens guide](../docs/refresh-tokens.html) for more information on how refresh tokens operate. ## Examples ```js client .refreshTokens({ refreshToken: 'eyJ0eXAiOiJKV1QiL...', scope: 'openid profile phone full_write' }) .then(authResult => { // Retrieves the refresh token }) .catch(err => console.error(err)) ``` ## Parameters ##### refreshToken string The refresh token used to generate the new refresh token. ##### scope string List of space-delimited, case-sensitive strings representing the requested scope. ## Response Type: `Promise` ### AuthResult object fields ##### accessToken `string` ##### expiresIn `number` ##### tokenType `string` This is always `Bearer`. ##### refreshToken `string` A refresh token is not present unless you are implementing the refresh token grant. This is only possible when the `offline_access` [scope](../docs/scope.html) is requested. ##### idToken `string` _Claims_ are pieces of information made about a particular subject. For example, ID tokens might contain a claim called `name` that makes the claim that the name of the user authenticating is "Nicole Dubois". ```json { "sub": "987654321", "name": "Nicole Dubois", ... } ``` ##### idTokenPayload `JSON` For a full list of claims, check out the [JWT Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims). ##### code `string` ##### state `string` ##### stepUpToken `string` ##### amr `string` For more on `amr` values, see [here](https://www.rfc-editor.org/rfc/rfc8176.html). ##### providerName `string` This is only relevant for SLO and is not included in the auth response for other flows. ##### providerAccessToken `string` This is only relevant for SLO and is not included in the auth response for other flows. * * * #### ID token payload The possible claims to assert about an authenticated user are outlined in the table below. ##### authType `string` ##### birthdate `string` ##### email `string` ##### emailVerified `boolean` ##### exp `number` ##### familyName `string` Also known as surname or last name. ##### givenName `string` Also known as first name. ##### gender `string` Currently allowed values are `female`, `male` and `other`. ##### iat `number` ##### iss `string` ##### cico `string` ##### locale `string` ##### name `string` ##### newUser `boolean` ##### sub `string` ##### aud `string` ##### picture `string` ##### profile `string` ##### updatedAt `string` ##### auth\_time `number` --- # removeMfaEmail URL: /sdk-core/removeMfaEmail.html client.removeMfaEmail({ [accessToken](#freshAccessToken): string }) ## About this command Remove email for use as a second-factor MFA credential. ## Examples ```javascript client.removeMfaEmail({ accessToken: 'eyJ0eXAiOiJKV1QiL...' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ## Response Type: `Promise` --- # removeMfaPhoneNumber URL: /sdk-core/removeMfaPhoneNumber.html client.removeMfaPhoneNumber({ [accessToken](#freshAccessToken): string, [phoneNumber](#phoneNumber): string }) ## About this command Unregister a phone number from MFA credentials. ## Examples ```javascript client.removeMfaPhoneNumber({ accessToken: 'eyJ0eXAiOiJKV1QiL...', phoneNumber: '+33606060606' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ##### phoneNumber string The user’s phone number. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. ## Response Type: `Promise` --- # removeSessionDevice URL: /sdk-core/removeSessionDevice.html client.removeSessionDevice({ [accessToken](#accessToken): string, [sessionDeviceId](#sessionDeviceId): string }) ## About this command Removes a specific session device for the authenticated user, forcing that device to reauthenticate. > The access token must include the `session` or `full_write` scope. If the user is enrolled in [MFA](../docs/mfa.html), the token must also include the `amr:mfa` claim. ## Examples ```javascript client.removeSessionDevice({ accessToken: 'eyJ0eXAiOiJKV1QiL...', sessionDeviceId: 'ABCDE12345' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API. ##### sessionDeviceId string The ID of the session device to remove. ## Response Type: `Promise` --- # removeWebAuthnDevice URL: /sdk-core/removeWebAuthnDevice.html client.removeWebAuthnDevice( [accessToken](#freshAccessToken): string, [deviceId](#deviceId): string ) ## About this command When authenticated, the user can remove a registered FIDO2 device. > - The WebAuthn feature must be enabled on your Purse Identity account. > ## Examples ```javascript client.removeWebAuthnDevice('eyJ0eXAiOiJKV1QiL...', 'AcfbMjJcS7vE46R3WHOJL...') ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ##### deviceId string The identifier of the device. ## Response Type: `Promise[void]` --- # requestPasswordReset URL: /sdk-core/requestPasswordReset.html // Request password reset with email client.requestPasswordReset({ [email](#email): string, // Optional arguments [redirectUrl](#redirectUrl): string, [returnToAfterPasswordReset](#returnToAfterPasswordReset): string, **(1)** [loginLink](#loginLink): string, [captchaToken](#captchaToken): string, [captchaProvider](#captchaProvider): string, [origin](#origin): string }) // Request password reset with phone number client.requestPasswordReset({ [phoneNumber](#phoneNumber): string, [origin](#origin): string, [captchaToken](#captchaToken): string [captchaProvider](#captchaProvider): string }) - (1) This parameter should only be used with [Hosted Pages](../docs/hosted-pages.html). ## About this command Request a password reset for the given email or phone number. On success, an email or an SMS with a reset token is sent to the user. ## Examples ```javascript client.requestPasswordReset({ email: 'john.doe@example.com', redirectUrl: 'https://example-password-reset.com' }) ``` ```javascript client.requestPasswordReset({ phoneNumber: '+33682234940' }) ``` ## Parameters ##### origin string Free text parameter describing the source of the action (e.g, login, password reset request). ##### captchaToken string Pass along the response token you have received from the captcha provider. - For reCAPTCHA, see [Google’s documentation on how to obtain it](https://developers.google.com/recaptcha/docs/v3) - For CaptchaFox, see [CaptchaFox’s documentation on how to obtain it](https://docs.captchafox.com/) Defaults to `null`. ##### captchaProvider string The captcha provider. This is one of the following: - `recaptcha` - `captchafox` ##### email string The user’s email address. ##### loginLink string The login URL the user will be redirected to after requesting password reset. This attribute can be used in a user interface. ##### phoneNumber string The user’s phone number. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. ##### redirectUrl string The URL sent in the email to which the user is redirected. This URL must be whitelisted in the `Allowed Callback URLs` field of your Purse Identity client settings. ##### returnToAfterPasswordReset string Returned in the `redirectUrl` as a query parameter, this parameter is used to redirect users to a specific URL after a password reset. > This parameter should only be used with [Hosted Pages](../docs/hosted-pages.html). This parameter should only be used with [Hosted Pages](../docs/hosted-pages.html). ## Response Type: `Promise[void]` --- # sendEmailVerification URL: /sdk-core/sendEmailVerification.html client.sendEmailVerification({ [accessToken](#accessToken): string, // Optional parameters [redirectUrl](#redirectUrl): string, [returnToAfterEmailConfirmation](#returnToAfterEmailConfirmation): string **(1)** }) - (1) This parameter should only be used with [Hosted Pages](../docs/hosted-pages.html). ## About this command Request the verification of the email address of a profile. If there is an email address configured in the profile that was not already verified, sends an email to verify it. ## Examples ```javascript client.sendEmailVerification({ accessToken: 'eyJ0eXAiOiJKV1QiL...', redirectUrl: 'https://example-email-verification.com' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API. ##### redirectUrl string The URL sent in the email to which the user is redirected. This URL must be whitelisted in the `Allowed Callback URLs` field of your Purse Identity client settings. ##### returnToAfterEmailConfirmation string Returned in the `redirectUrl` as a query parameter, this parameter is used as the post-email confirmation URL. > This parameter should only be used with [Hosted Pages](../docs/hosted-pages.html). This parameter should only be used with [Hosted Pages](../docs/hosted-pages.html). ## Response Type: `Promise[void]` --- # sendPhoneNumberVerification URL: /sdk-core/sendPhoneNumberVerification.html client.sendPhoneNumberVerification({ [accessToken](#accessToken): string }) ## About this command Request the verification of the phone number of a profile. If there is a phone number configured in the profile that was not already verified, and the SMS feature is activated, sends an SMS to verify it. ## Examples ```javascript client.sendPhoneNumberVerification({ accessToken: 'eyJ0eXAiOiJKV1QiL...' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API. ## Response Type: `Promise[void]` --- # signup URL: /sdk-core/signup.html client.signup({ [data](#data): SignupProfile, // Optional parameters [saveCredentials](#saveCredentials): boolean, [redirectUrl](#redirectUrl): string, [returnToAfterEmailConfirmation](#returnToAfterEmailConfirmation): string, **(1)** [captchaToken](#captchaToken): string, [captchaProvider](#captchaProvider): string, [auth](#auth): AuthOptions }) - (1) This parameter should only be used with [Hosted Pages](../docs/hosted-pages.html). ## About this command Create and authenticate a new user with the specified data. A user may identify himself with either his email address or his phone number. ## Examples ```javascript client .signup({ data: { givenName: 'John', familyName: 'Doe', email: 'john.doe@example.com', password: 'N5uiKvve' }, redirectUrl: 'https://example-email-validate.com' }) .then(authResult => { // Retrieve the access token }) .catch(err => console.error(err)) ``` ## Parameters ##### options AuthOptions List of authentication options ##### responseType string The desired OAuth2 grant type. Use `code` to request an authorization code (recommended), `id_token` to request an ID token, or `token` for a token set (implicit grant, discouraged). > Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. ##### redirectUri string The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified `state` string will also be included. This parameter is required with `code` response type and defaults to the current page with `token` response type. `redirectUri` is still required when setting `useWebMessage` to `true` despite there being no redirection involved. ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### prompt string Specify whether the flow should explicitly prompt the user for reauthentication or not. > This applies to the Login with session flow where a session cookie is provided. > In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. The defined values are: - `none`: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent. > If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. - `login`: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the `redirect_uri` or client-configured login URL (if no `redirect_uri` is specified). - `consent`: The flow should prompt for consent, otherwise an error must be returned to the client (`consent_required`). This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### popupMode boolean Whether or not to use popup mode. Defaults to `false`. > This mode is not recommended due to known bugs in Android or Firefox in iOS. This mode is not recommended due to known bugs in Android or Firefox in iOS. ##### useWebMessage boolean When set to `true`, the SDK will leverage the `web_message` response mode in order to avoid having to redirect the user-agent to obtain the authorization response. Defaults to `false`. If set to `true` and `responseType` is `code`, the authorization code will be automatically exchanged at the token endpoint along with any potential `code_verifier`. ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### accessToken string Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old). ##### providerScope string List of space-delimited, case-sensitive strings representing the requested scope at the social provider. Defaults to the scope configured for the given provider in your Purse Identity Console. > Only for login with social provider. Only for login with social provider. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### returnProviderToken boolean Boolean that specifies whether you should return the provider access token. Defaults to `false`. If set to `true`, you retrieve the provider and provider access token as part of the [authentication result](../docs/models-auth-result.html). Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. This mode is not recommended due to known bugs in Android or Firefox in iOS. Only for login with social provider. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### captchaToken string Pass along the response token you have received from the captcha provider. - For reCAPTCHA, see [Google’s documentation on how to obtain it](https://developers.google.com/recaptcha/docs/v3) - For CaptchaFox, see [CaptchaFox’s documentation on how to obtain it](https://docs.captchafox.com/) Defaults to `null`. ##### captchaProvider string The captcha provider. This is one of the following: - `recaptcha` - `captchafox` ##### redirectUrl string The URL sent in the email to which the user is redirected. This URL must be whitelisted in the `Allowed Callback URLs` field of your Purse Identity client settings. ##### returnToAfterEmailConfirmation string Returned in the `redirectUrl` as a query parameter, this parameter is used as the post-email confirmation URL. > This parameter should only be used with [Hosted Pages](../docs/hosted-pages.html). This parameter should only be used with [Hosted Pages](../docs/hosted-pages.html). ##### saveCredentials boolean Store the user credentials with the Credentials Management API. Defaults to `false`. > This feature is experimental, please check your [browser compatibility](https://caniuse.com/#feat=credential-management). This feature is experimental, please check your [browser compatibility](https://caniuse.com/#feat=credential-management). ##### data SignupProfile The data of the profile. ##### password string The password of the profile. Password must meet the minimum requirements defined by the [zxcvbn](https://github.com/dropbox/zxcvbn) used. ##### email string The primary email address of the profile. ##### phoneNumber string The primary phone number of the profile. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. ##### customIdentifier string A string that allows users to authenticate with something other than an `email` or `phone_number`. It’s important to note that an `email` and/or `phone_number` is still required to create a managed profile. Each `custom_identifier` value must be unique. The `custom_identifier` must be between _4-80_ characters. ##### givenName string The given name of the profile. ##### middleName string The middle name of the profile. ##### familyName string The family name of the profile. ##### name string The full name of the profile. ##### nickname string The nickname of the profile. ##### birthdate string The birthdate of the profile, represented as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) `YYYY-MM-DD` format. ##### profileURL string The URL of one of the user’s profile page (generally a social provider’s page). ##### picture string The URL of one of the profile picture. This URL refers to an image file (PNG, JPEG, or GIF image file). ##### username string The username of the profile (the login’s name). ##### gender string The gender of the profile. Allowed values are `female`, `male` and `other`. ##### company string The company’s name of the profile. ##### addresses List of ProfileAddress The list of the profile’s postal addresses. ##### locale string The profile’s language code in lowercase and country code in uppercase, separated by a dash (e.g. en, fr-FR …​). ##### bio string The biography of the profile. ##### customFields Record The custom fields of the profile. ##### consents Record The consents granted to the profile. It is a map of string keys with the associated consent object. ## Response Type: `Promise` ### AuthResult object fields ##### accessToken `string` ##### expiresIn `number` ##### tokenType `string` This is always `Bearer`. ##### refreshToken `string` A refresh token is not present unless you are implementing the refresh token grant. This is only possible when the `offline_access` [scope](../docs/scope.html) is requested. ##### idToken `string` _Claims_ are pieces of information made about a particular subject. For example, ID tokens might contain a claim called `name` that makes the claim that the name of the user authenticating is "Nicole Dubois". ```json { "sub": "987654321", "name": "Nicole Dubois", ... } ``` ##### idTokenPayload `JSON` For a full list of claims, check out the [JWT Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims). ##### code `string` ##### state `string` ##### stepUpToken `string` ##### amr `string` For more on `amr` values, see [here](https://www.rfc-editor.org/rfc/rfc8176.html). ##### providerName `string` This is only relevant for SLO and is not included in the auth response for other flows. ##### providerAccessToken `string` This is only relevant for SLO and is not included in the auth response for other flows. * * * #### ID token payload The possible claims to assert about an authenticated user are outlined in the table below. ##### authType `string` ##### birthdate `string` ##### email `string` ##### emailVerified `boolean` ##### exp `number` ##### familyName `string` Also known as surname or last name. ##### givenName `string` Also known as first name. ##### gender `string` Currently allowed values are `female`, `male` and `other`. ##### iat `number` ##### iss `string` ##### cico `string` ##### locale `string` ##### name `string` ##### newUser `boolean` ##### sub `string` ##### aud `string` ##### picture `string` ##### profile `string` ##### updatedAt `string` ##### auth\_time `number` --- # signupWithWebAuthn URL: /sdk-core/signupWithWebAuthn.html client.signupWithWebAuthn( [params](#params): SignupWithWebAuthnParams, // Optional arguments [auth](#auth): AuthOptions ) ## About this command The user requests to register a new account for the first time. The server verifies the signup data, registers a new user, and sends a verification code or token to the provided email address. > The WebAuthn feature must be enabled on your Purse Identity account. ## Examples ```javascript client .signupWithWebAuthn( { profile: { givenName: 'John', familyName: 'Doe', email: 'john.doe@example.com', birthdate: '1983-11-13' }, friendlyName: 'passkey', redirectUrl: 'https://example-email-validate.com' } ) .then(authResult => { // Retrieve the access token }) .catch(err => console.error(err)) ``` ## Parameters ##### params SignupWithWebAuthnParams The parameters required to signup with WebAuthn ##### profile SignupProfileData The profile data. > This typically consists of `givenName`, `familyName`, `email`, and `birthdate`. This typically consists of `givenName`, `familyName`, `email`, and `birthdate`. ##### friendlyName string The name of the FIDO2 device. > Each device must have a unique name. This defaults to the platform of the browser. Each device must have a unique name. This defaults to the platform of the browser. ##### redirectUrl string The URL to which the profile is redirected. > This is sent in the confirmation email. This is sent in the confirmation email. ##### returnToAfterEmailConfirmation string Returned in the `redirectUrl` as a query parameter, this parameter is used as the post-email confirmation URL. > This parameter should only be used with [Hosted Pages](../docs/hosted-pages.html). This parameter should only be used with [Hosted Pages](../docs/hosted-pages.html). This typically consists of `givenName`, `familyName`, `email`, and `birthdate`. Each device must have a unique name. This defaults to the platform of the browser. This is sent in the confirmation email. This parameter should only be used with [Hosted Pages](../docs/hosted-pages.html). ##### options AuthOptions List of authentication options ##### responseType string The desired OAuth2 grant type. Use `code` to request an authorization code (recommended), `id_token` to request an ID token, or `token` for a token set (implicit grant, discouraged). > Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. ##### redirectUri string The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified `state` string will also be included. This parameter is required with `code` response type and defaults to the current page with `token` response type. `redirectUri` is still required when setting `useWebMessage` to `true` despite there being no redirection involved. ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### prompt string Specify whether the flow should explicitly prompt the user for reauthentication or not. > This applies to the Login with session flow where a session cookie is provided. > In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. The defined values are: - `none`: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent. > If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. - `login`: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the `redirect_uri` or client-configured login URL (if no `redirect_uri` is specified). - `consent`: The flow should prompt for consent, otherwise an error must be returned to the client (`consent_required`). This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### popupMode boolean Whether or not to use popup mode. Defaults to `false`. > This mode is not recommended due to known bugs in Android or Firefox in iOS. This mode is not recommended due to known bugs in Android or Firefox in iOS. ##### useWebMessage boolean When set to `true`, the SDK will leverage the `web_message` response mode in order to avoid having to redirect the user-agent to obtain the authorization response. Defaults to `false`. If set to `true` and `responseType` is `code`, the authorization code will be automatically exchanged at the token endpoint along with any potential `code_verifier`. ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### accessToken string Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old). ##### providerScope string List of space-delimited, case-sensitive strings representing the requested scope at the social provider. Defaults to the scope configured for the given provider in your Purse Identity Console. > Only for login with social provider. Only for login with social provider. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### returnProviderToken boolean Boolean that specifies whether you should return the provider access token. Defaults to `false`. If set to `true`, you retrieve the provider and provider access token as part of the [authentication result](../docs/models-auth-result.html). Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. This mode is not recommended due to known bugs in Android or Firefox in iOS. Only for login with social provider. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ## Response Type: `Promise` ### AuthResult object fields ##### accessToken `string` ##### expiresIn `number` ##### tokenType `string` This is always `Bearer`. ##### refreshToken `string` A refresh token is not present unless you are implementing the refresh token grant. This is only possible when the `offline_access` [scope](../docs/scope.html) is requested. ##### idToken `string` _Claims_ are pieces of information made about a particular subject. For example, ID tokens might contain a claim called `name` that makes the claim that the name of the user authenticating is "Nicole Dubois". ```json { "sub": "987654321", "name": "Nicole Dubois", ... } ``` ##### idTokenPayload `JSON` For a full list of claims, check out the [JWT Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims). ##### code `string` ##### state `string` ##### stepUpToken `string` ##### amr `string` For more on `amr` values, see [here](https://www.rfc-editor.org/rfc/rfc8176.html). ##### providerName `string` This is only relevant for SLO and is not included in the auth response for other flows. ##### providerAccessToken `string` This is only relevant for SLO and is not included in the auth response for other flows. * * * #### ID token payload The possible claims to assert about an authenticated user are outlined in the table below. ##### authType `string` ##### birthdate `string` ##### email `string` ##### emailVerified `boolean` ##### exp `number` ##### familyName `string` Also known as surname or last name. ##### givenName `string` Also known as first name. ##### gender `string` Currently allowed values are `female`, `male` and `other`. ##### iat `number` ##### iss `string` ##### cico `string` ##### locale `string` ##### name `string` ##### newUser `boolean` ##### sub `string` ##### aud `string` ##### picture `string` ##### profile `string` ##### updatedAt `string` ##### auth\_time `number` --- # startMfaEmailRegistration URL: /sdk-core/startMfaEmailRegistration.html client.startMfaEmailRegistration({ [accessToken](#freshAccessToken): string, // Optional arguments [trustDevice](#trustDevice): boolean, **(1)** [redirectUrl](#redirectUrl): string, [action](#action): string }) - (1) If the email is already verified and you set `trust_device` to `true`, the `__Host-trusted-device-id` cookie is deposited in the response header and you do not need to pass `trust_device` in the [verifyMfaEmailRegistration](verifyMfaEmailRegistration.html) step. ## About this command Starts the MFA email registration flow. When started, an email is sent to the user for verification. > If the user already has a verified email as an identifier in their account, no additional verification code is sent. > > If an existing email exists but is unverified, it becomes automatically verified with [verifyMfaEmailRegistration](verifyMfaEmailRegistration.html). ## Examples ```javascript client.startMfaEmailRegistration({ accessToken: 'eyJ0eXAiOiJKV1QiL...', redirectUrl: 'https://example.com/redirect', action: 'stepup' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ##### trustDevice boolean Boolean indicating if the device should be trusted or not. Defaults to `false`. ##### redirectUrl string The URL sent in the email to which the user is redirected. This URL must be whitelisted in the `Allowed Callback URLs` field of your Purse Identity client settings. ##### action string A string describing the action for the MFA flow. You can value this with whatever you like. It should match the value you describe in your [MFA templates](../docs/mfa-templates.html). We recommend using meaningful values like `login` or `transaction` to help better align with MFA email and SMS templates. ## Response Type: `Promise` --- # startMfaPhoneNumberRegistration URL: /sdk-core/startMfaPhoneNumberRegistration.html client.startMfaPhoneNumberRegistration({ [accessToken](#freshAccessToken): string, [phoneNumber](#phoneNumber): string, **(1)** [trustDevice](#trustDevice): boolean, **(2)** [action](#action): string }) - (1) If the user already has a verified phone number as an identifier in their account, there’s no need to pass the `phoneNumber` parameter. - (2) If the phone number is already verified and you set `trust_device` to `true`, the `__Host-trusted-device-id` cookie is deposited in the response header and you do not need to pass `trust_device` in the [verifyMfaPhoneNumberRegistration](verifyMfaPhoneNumberRegistration.html) step. > If an existing phone number is unverified, it becomes automatically verified with the [verifyMfaPhoneNumberRegistration](verifyMfaPhoneNumberRegistration.html) step. ## About this command Starts the MFA phone number registration flow. When started, an SMS is sent to the user for verification. ## Examples ```javascript client.startMfaPhoneNumberRegistration({ accessToken: 'eyJ0eXAiOiJKV1QiL...', phoneNumber: '+33606060606', action: 'stepup' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ##### phoneNumber string The user’s phone number. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. ##### trustDevice boolean Boolean indicating if the device should be trusted or not. Defaults to `false`. ##### action string A string describing the action for the MFA flow. You can value this with whatever you like. It should match the value you describe in your [MFA templates](../docs/mfa-templates.html). We recommend using meaningful values like `login` or `transaction` to help better align with MFA email and SMS templates. ## Response Type: `Promise` --- # startPasswordless URL: /sdk-core/startPasswordless.html client.startPasswordless( [params](#params): PasswordlessParams, // Optional parameters [captchaToken](#captchaToken): string, [captchaProvider](#captchaProvider): string, [auth](#auth): AuthOptions ) client.startPasswordless( [stepUp](#parameters): string, // Optional parameters [captchaToken](#captchaToken): string, [captchaProvider](#captchaProvider): string, [auth](#auth): AuthOptions ) ## About this command Starts passwordless flow by sending an email or SMS to the user with a single-use auth code or access token (depending on the response type). > - The Passwordless feature must be enabled on your Purse Identity Console account. > > - The SMS feature must be enabled on your Purse Identity Console account if the profile can choose a phone number to login. > > > PKCE expects the same client context to complete both steps of the exchange. This means that if a user starts the flow on one device and then tries to complete it on a different device (e.g., by switching from mobile to tablet), the exchange fails. ## Examples ```javascript client.startPasswordless( { authType: 'magic_link', email: 'john.doe@example.com' }, { redirectUri: 'https://www.example.com/login/callback' } ) ``` ```javascript client.startPasswordless({ authType: 'sms', phoneNumber: '+33612345678', redirectUri: 'https://www.example.com/login/callback' }) ``` ```javascript client.startPasswordless({ authType: 'sms', stepUp: '3y8HnXfn7Y...w9iuF2ele9LCuk' }) ``` ## Parameters ##### params PasswordlessParams The parameters for passwordless authentication. ##### authType string The type of passwordless authentication. Allowed values: \* `magic_link` \* `sms` ##### email string The primary email address of the profile. ##### phoneNumber string The primary phone number of the profile. > Both the international format and the national conventions of the account’s country are accepted if configured in account settings. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. ##### captchaToken string Pass along the response token you have received from the captcha provider. - For reCAPTCHA, see [Google’s documentation on how to obtain it](https://developers.google.com/recaptcha/docs/v3) - For CaptchaFox, see [CaptchaFox’s documentation on how to obtain it](https://docs.captchafox.com/) Defaults to `null`. ##### captchaProvider string The captcha provider. This is one of the following: - `recaptcha` - `captchafox` ##### options AuthOptions List of authentication options ##### responseType string The desired OAuth2 grant type. Use `code` to request an authorization code (recommended), `id_token` to request an ID token, or `token` for a token set (implicit grant, discouraged). > Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. ##### redirectUri string The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified `state` string will also be included. This parameter is required with `code` response type and defaults to the current page with `token` response type. `redirectUri` is still required when setting `useWebMessage` to `true` despite there being no redirection involved. ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### prompt string Specify whether the flow should explicitly prompt the user for reauthentication or not. > This applies to the Login with session flow where a session cookie is provided. > In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. The defined values are: - `none`: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent. > If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. - `login`: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the `redirect_uri` or client-configured login URL (if no `redirect_uri` is specified). - `consent`: The flow should prompt for consent, otherwise an error must be returned to the client (`consent_required`). This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### popupMode boolean Whether or not to use popup mode. Defaults to `false`. > This mode is not recommended due to known bugs in Android or Firefox in iOS. This mode is not recommended due to known bugs in Android or Firefox in iOS. ##### useWebMessage boolean When set to `true`, the SDK will leverage the `web_message` response mode in order to avoid having to redirect the user-agent to obtain the authorization response. Defaults to `false`. If set to `true` and `responseType` is `code`, the authorization code will be automatically exchanged at the token endpoint along with any potential `code_verifier`. ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### accessToken string Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old). ##### providerScope string List of space-delimited, case-sensitive strings representing the requested scope at the social provider. Defaults to the scope configured for the given provider in your Purse Identity Console. > Only for login with social provider. Only for login with social provider. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### returnProviderToken boolean Boolean that specifies whether you should return the provider access token. Defaults to `false`. If set to `true`, you retrieve the provider and provider access token as part of the [authentication result](../docs/models-auth-result.html). Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. This mode is not recommended due to known bugs in Android or Firefox in iOS. Only for login with social provider. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### params PasswordlessParams The parameters for passwordless authentication. ##### authType string The type of passwordless authentication. - `sms` ##### stepUp string The step up token for verification. ##### captchaToken string Pass along the response token you have received from the captcha provider. - For reCAPTCHA, see [Google’s documentation on how to obtain it](https://developers.google.com/recaptcha/docs/v3) - For CaptchaFox, see [CaptchaFox’s documentation on how to obtain it](https://docs.captchafox.com/) Defaults to `null`. ##### captchaProvider string The captcha provider. This is one of the following: - `recaptcha` - `captchafox` ##### options AuthOptions List of authentication options ##### responseType string The desired OAuth2 grant type. Use `code` to request an authorization code (recommended), `id_token` to request an ID token, or `token` for a token set (implicit grant, discouraged). > Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. ##### redirectUri string The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified `state` string will also be included. This parameter is required with `code` response type and defaults to the current page with `token` response type. `redirectUri` is still required when setting `useWebMessage` to `true` despite there being no redirection involved. ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### prompt string Specify whether the flow should explicitly prompt the user for reauthentication or not. > This applies to the Login with session flow where a session cookie is provided. > In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. The defined values are: - `none`: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent. > If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. - `login`: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the `redirect_uri` or client-configured login URL (if no `redirect_uri` is specified). - `consent`: The flow should prompt for consent, otherwise an error must be returned to the client (`consent_required`). This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### popupMode boolean Whether or not to use popup mode. Defaults to `false`. > This mode is not recommended due to known bugs in Android or Firefox in iOS. This mode is not recommended due to known bugs in Android or Firefox in iOS. ##### useWebMessage boolean When set to `true`, the SDK will leverage the `web_message` response mode in order to avoid having to redirect the user-agent to obtain the authorization response. Defaults to `false`. If set to `true` and `responseType` is `code`, the authorization code will be automatically exchanged at the token endpoint along with any potential `code_verifier`. ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### accessToken string Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old). ##### providerScope string List of space-delimited, case-sensitive strings representing the requested scope at the social provider. Defaults to the scope configured for the given provider in your Purse Identity Console. > Only for login with social provider. Only for login with social provider. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### returnProviderToken boolean Boolean that specifies whether you should return the provider access token. Defaults to `false`. If set to `true`, you retrieve the provider and provider access token as part of the [authentication result](../docs/models-auth-result.html). Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. This mode is not recommended due to known bugs in Android or Firefox in iOS. Only for login with social provider. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ## Response Type: `Promise[void]` ## Next step (MFA flow) The next step after the `startPasswordless` method in the MFA flow is: [verifyMfaPasswordless](verifyMfaPasswordless.html) > See the [dedicated MFA guide for more details](../docs/mfa.html). --- # unlink URL: /sdk-core/unlink.html client.unlink({ [accessToken](#freshAccessToken): string, [identityId](#identityId): string, // Optional fields [fields](#fields): string, }) ## About this command Unlink social account from the current user. Return the updated user. > If this is the only method of authentication for the user, the user profile is deleted. ## Examples ```javascript client.unlink({ accessToken: 'eyJ0eXAiOiJKV1QiL...', identityId: 'facebook:123456789...' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ##### identityId string The identity ID to remove. ##### fields string The user fields to fetch in the response. Defaults to `id,name,email`. ## Response Type: `Promise[void]` --- # updateEmail URL: /sdk-core/updateEmail.html client.updateEmail({ [accessToken](#freshAccessToken): string, [email](#updateEmail): string, [captchaToken](#captchaToken): string, [captchaProvider](#captchaProvider): string, // Optional fields [redirectUrl](#redirectUrl): string, }) ## About this command Update the profile’s email address and send a verification email. > - The profile must have been granted the `full_write` scope at the last authentication. > > - It is required to configure and enable the [Email update template](../docs/email-templates.html) in the account’s settings. > ## Examples ```javascript client.updateEmail({ accessToken: 'eyJ0eXAiOiJKV1QiL...', email: 'johnatthan.doe@gmail.com', captchaToken: 'pyJ0e9WiOimld1Qiqm', captchaProvider: 'recaptcha', redirectUrl: 'https://example-email-update.com' }) ``` ## Parameters ##### captchaToken string Pass along the response token you have received from the captcha provider. - For reCAPTCHA, see [Google’s documentation on how to obtain it](https://developers.google.com/recaptcha/docs/v3) - For CaptchaFox, see [CaptchaFox’s documentation on how to obtain it](https://docs.captchafox.com/) Defaults to `null`. ##### captchaProvider string The captcha provider. This is one of the following: - `recaptcha` - `captchafox` ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ##### redirectUrl string The URL sent in the email to which the user is redirected. This URL must be whitelisted in the `Allowed Callback URLs` field of your Purse Identity client settings. ##### email string The email address of the profile. The new email address must be different from the old one. Unverified emails If the email being updated is unverified, the user’s email is updated immediately. Verified emails If the email being updated is verified, the user must click on the verification link sent in the email to finish the _update email flow_. Users won’t be able to use the new email for authentication until it is verified. > For more, see our [Email address management page](../docs/email-address-management.html#changing-email-address-when-logged-in). For more, see our [Email address management page](../docs/email-address-management.html#changing-email-address-when-logged-in). ## Response Type: `Promise[void]` --- # updatePassword URL: /sdk-core/updatePassword.html // Update a password with the old password client.updatePassword({ [password](#password): string, // Optional fields [accessToken](#accessToken): string, [oldPassword](#oldPassword): string }) // Update a password with the email client.updatePassword({ [email](#email): string, [verificationCode](#verificationCode): string, [password](#password): string, // Optional fields [accessToken](#accessToken): string }) // Update a password with the phone number client.updatePassword({ [phoneNumber](#phoneNumber): string, [verificationCode](#verificationCode): string, [password](#password): string, // Optional fields [accessToken](#accessToken): string }) ## About this command Update the profile’s password. The parameters required in addition to the new password are either: - A fresh access token (less than 5 minutes old). - An access token and the old password. - The profile’s email address/phone number and the verification code sent by email/SMS through a request password reset flow. > - The profile must have been granted the `full_write` scope at the last authentication. > ## Examples ```javascript client.updatePassword({ accessToken: 'eyJ0eXAiOiJKV1QiL...', password: 'ZPf7LFtc', oldPassword: 'gVc7piBn' }) ``` ```javascript client.updatePassword({ accessToken: 'eyJ0eXAiOiJKV1QiL...', password: 'ZPf7LFtc' }) ``` ```javascript client.updatePassword({ email: 'john.doe@example.com', verificationCode: '234', password: 'ZPf7LFtc' }) ``` ```javascript client.updatePassword({ phoneNumber: '+33682234940', verificationCode: '234', password: 'ZPf7LFtc' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API. ##### password string The user’s password. ##### oldPassword string The old password of the profile. ##### verificationCode string The verification code sent by email or SMS. ##### email string The user’s email address. ##### phoneNumber string The user’s phone number. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. ## Response Type: `Promise[void]` --- # updatePhoneNumber URL: /sdk-core/updatePhoneNumber.html client.updatePhoneNumber({ [accessToken](#freshAccessToken): string, [phoneNumber](#phoneNumber): string }) ## About this command Update the profile phone number and send a verification code by SMS. > - The profile must have been granted the `full_write` scope at the last authentication. > > - It is required to configure and to enable the _Verification SMS_ template in the account’s settings. > ## Examples ```javascript client.updatePhoneNumber({ accessToken: 'eyJ0eXAiOiJKV1QiL...', phoneNumber: '+33606060606' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ##### phoneNumber string The user’s phone number. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. ## Response Type: `Promise[void]` --- # updateProfile URL: /sdk-core/updateProfile.html client.updateProfile({ [accessToken](#accessToken): string, [redirectUrl](#redirectUrl): string, [data](#profile): Profile }) ## About this command Update the information of the profile. > - The profile must have been granted the `full_write` scope at the last authentication. > > - The `email` and the `password` fields of the profile can’t be updated with this method, except if the profile has no email address (usually when it is not provided by the social provider). Instead, use the [updateEmail](updateEmail.html) method. > > - The `phoneNumber` field of the profile can’t be updated if the SMS verification code is disabled on the account settings. > ## Examples ```javascript client.updateProfile({ accessToken: 'eyJ0eXAiOiJKV1QiL...', redirectUrl: 'https://example-email-validate.com', data: { givenName: 'John', familyName: 'Doe' } }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API. ##### redirectUrl string The URL sent in the email to which the user is redirected. This URL must be whitelisted in the `Allowed Callback URLs` field of your Purse Identity client settings. ##### profile Profile The profile with the new data. Only the provided fields will be updated. ##### password string The password of the profile. Password must meet the minimum requirements defined by the [zxcvbn](https://github.com/dropbox/zxcvbn) used. ##### email string The primary email address of the profile. ##### phoneNumber string The primary phone number of the profile. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. ##### givenName string The given name of the profile. ##### middleName string The middle name of the profile. ##### familyName string The family name of the profile. ##### name string The full name of the profile. ##### nickname string The nickname of the profile. ##### birthdate string The birthdate of the profile, represented as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) `YYYY-MM-DD` format. ##### profileURL string The URL of one of the user’s profile page (usually a social provider’s page). ##### picture string The URL of one of the profile picture. This URL refers to an image file (PNG, JPEG, or GIF image file). ##### username string The username of the profile (the login’s name). ##### gender string The gender of the profile. Allowed values are `female`, `male` and `other`. ##### company string The company’s name of the profile. ##### addresses ProfileAddress\[\] The list of the profile’s postal addresses ##### locale string The profile’s language code in lowercase and country code in uppercase, separated by a dash (for instance: `en`, `fr-FR`…​). ##### bio string The biography of the profile. ##### customFields Map The custom fields of the profile. ##### consents Map The consents granted to the profile. It is a map of string keys with the associated consent object. ## Response Type: `Promise[void]` --- # verifyEmail URL: /sdk-core/verifyEmail.html client.verifyEmail({ [accessToken](#freshAccessToken): string, [email](#email): string, [verificationCode](#verificationCode): string }) ## About this command Verify the profile’s email with a verification code. > The profile must have been granted the `full_write` scope at the last authentication. ## Examples ```javascript client.verifyEmail({ accessToken: 'eeJ1eXAiOiJKV1QiL...', email: 'first.last@example.com', verificationCode: '123456' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ##### email string The user’s email address. ##### verificationCode string The verification code sent by email or SMS. ## Response Type: `Promise[void]` --- # verifyMfaEmailRegistration URL: /sdk-core/verifyMfaEmailRegistration.html client.verifyMfaEmailRegistration({ [accessToken](#accessToken): string, [verificationCode](#verificationCode): string, [trustDevice](#trustDevice): boolean }) ## About this command Completes the email registration process for use as a second factor credential (MFA). ## Examples ```javascript client.verifyMfaEmailRegistration({ accessToken: 'eyJ0eXAiOiJKV1QiL...', verificationCode: '13..31' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API. ##### verificationCode string The verification code sent by email or SMS. ##### trustDevice boolean Boolean indicating if the device should be trusted or not. Defaults to `false`. ## Response Type: `Promise` --- # verifyMfaPasswordless URL: /sdk-core/verifyMfaPasswordless.html client.verifyMfaPasswordless({ [params](#params): VerifyMfaPasswordlessParams }) ## About this command Verifies the passwordless flow for MFA with the user `verification_code` and `challenge_id`. > - The Passwordless feature must be enabled on your Purse Identity Console account. > > - The SMS feature must be enabled on your Purse Identity Console account if you want mobile numbers to be available as a login option. > ## Examples ```javascript client.verifyMfaPasswordless({ challengeId: 'm3DaoT...7Rzp1m', verificationCode: '123456' }) ``` ## Parameters ##### params VerifyPasswordlessParams The parameters of the passwordless verify authentication. ##### challengeId string The code challenge ID to verify the user. ##### verificationCode string The verification code sent by email or SMS. ##### trustDevice boolean Boolean indicating if the device should be trusted or not. - `true` = trust the device - `false` = do not trust the device ## Response Type: `Promise` ### AuthResult object fields ##### accessToken `string` ##### expiresIn `number` ##### tokenType `string` This is always `Bearer`. ##### refreshToken `string` A refresh token is not present unless you are implementing the refresh token grant. This is only possible when the `offline_access` [scope](../docs/scope.html) is requested. ##### idToken `string` _Claims_ are pieces of information made about a particular subject. For example, ID tokens might contain a claim called `name` that makes the claim that the name of the user authenticating is "Nicole Dubois". ```json { "sub": "987654321", "name": "Nicole Dubois", ... } ``` ##### idTokenPayload `JSON` For a full list of claims, check out the [JWT Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims). ##### code `string` ##### state `string` ##### stepUpToken `string` ##### amr `string` For more on `amr` values, see [here](https://www.rfc-editor.org/rfc/rfc8176.html). ##### providerName `string` This is only relevant for SLO and is not included in the auth response for other flows. ##### providerAccessToken `string` This is only relevant for SLO and is not included in the auth response for other flows. * * * #### ID token payload The possible claims to assert about an authenticated user are outlined in the table below. ##### authType `string` ##### birthdate `string` ##### email `string` ##### emailVerified `boolean` ##### exp `number` ##### familyName `string` Also known as surname or last name. ##### givenName `string` Also known as first name. ##### gender `string` Currently allowed values are `female`, `male` and `other`. ##### iat `number` ##### iss `string` ##### cico `string` ##### locale `string` ##### name `string` ##### newUser `boolean` ##### sub `string` ##### aud `string` ##### picture `string` ##### profile `string` ##### updatedAt `string` ##### auth\_time `number` ## Validate MFA flow If you are using the `verifyMfaPasswordless` method as part of the MFA flow. You can decode the token or use the [Introspect token](https://docs.identity.purse.eu/openapi/identity.html#operation/introspectToken) to validate MFA for the user. > See the [dedicated MFA guide for more details](../docs/mfa.html). --- # verifyMfaPhoneNumberRegistration URL: /sdk-core/verifyMfaPhoneNumberRegistration.html client.verifyMfaPhoneNumberRegistration({ [accessToken](#accessToken): string, [verificationCode](#verificationCode): string, [trustDevice](#trustDevice): boolean }) ## About this command Completes the phone number as a second factor registration process. It also automatically verifies the existing phone number for the user. ## Examples ```javascript client.verifyMfaPhoneNumberRegistration({ accessToken: 'eyJ0eXAiOiJKV1QiL...', verificationCode: '13..31' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API. ##### verificationCode string The verification code sent by email or SMS. ##### trustDevice boolean Boolean indicating if the device should be trusted or not. Defaults to `false`. ## Response Type: `Promise` --- # verifyPasswordless URL: /sdk-core/verifyPasswordless.html client.verifyPasswordless( [params](#params): VerifyPasswordlessParams, // Optional fields [auth](#auth): AuthOptions ) ## About this command Log in a user by initiating the authentication code flow using the SMS verification code or by clicking on the link provided in the email. > - The Passwordless feature must be enabled on your Purse Identity Console account. > > - The SMS feature must be enabled on your Purse Identity Console account if the profile can choose a phone number to login. > > > PKCE expects the same client context to complete both steps of the exchange. This means that if a user starts the flow on one device and then tries to complete it on a different device (e.g., by switching from mobile to tablet), the exchange fails. ## Examples ```javascript client.verifyPasswordless( { email: 'john.doe@example.com', verificationCode: '123456', authType: 'magic_link' }, { redirectUri: 'https://www.example.com/login/callback' } ) ``` ```javascript client.verifyPasswordless({ phoneNumber: '+33606060606', verificationCode: '123456', authType: 'sms' }) ``` ## Parameters ##### params VerifyPasswordlessParams The parameters of the passwordless verify authentication. ##### verificationCode string The verification code sent by email or SMS. ##### authType string The type of passwordless authentication. Allowed values: `magic_link` or `sms`. ##### email string The primary email address of the profile. ##### phoneNumber string The primary phone number of the profile. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. ##### options AuthOptions List of authentication options ##### responseType string The desired OAuth2 grant type. Use `code` to request an authorization code (recommended), `id_token` to request an ID token, or `token` for a token set (implicit grant, discouraged). > Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. ##### redirectUri string The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified `state` string will also be included. This parameter is required with `code` response type and defaults to the current page with `token` response type. `redirectUri` is still required when setting `useWebMessage` to `true` despite there being no redirection involved. ##### state string An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery as described in [Section 10.12 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-10.12). ##### prompt string Specify whether the flow should explicitly prompt the user for reauthentication or not. > This applies to the Login with session flow where a session cookie is provided. > In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. The defined values are: - `none`: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent. > If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. - `login`: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the `redirect_uri` or client-configured login URL (if no `redirect_uri` is specified). - `consent`: The flow should prompt for consent, otherwise an error must be returned to the client (`consent_required`). This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. ##### nonce string String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See [Section 15.5.2](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) of OpenID Connect for more implementation details. ##### persistent boolean When `persistent` is `true`, the session duration configured in the Purse Identity Console (**Settings**  **Security**  **SSO**) applies. If `persistent` is not set or is `false`, the default session duration of 1 day applies. Defaults to `true`. ##### popupMode boolean Whether or not to use popup mode. Defaults to `false`. > This mode is not recommended due to known bugs in Android or Firefox in iOS. This mode is not recommended due to known bugs in Android or Firefox in iOS. ##### useWebMessage boolean When set to `true`, the SDK will leverage the `web_message` response mode in order to avoid having to redirect the user-agent to obtain the authorization response. Defaults to `false`. If set to `true` and `responseType` is `code`, the authorization code will be automatically exchanged at the token endpoint along with any potential `code_verifier`. When set to `true`, `verifyPasswordless` sends back the [`AuthResult`](#response). Otherwise, the method responds with [`void`](#response). ##### origin string Free text parameter describing the source of the login (only for reporting purposes). ##### scope string\[\] List of space-delimited, case-sensitive strings representing the requested scope. Optional if the `fetchBasicProfile` option is set to `true` and the `profile`, `email`, `phone` and `openid` scope values are allowed in client configuration. ##### fetchBasicProfile boolean Fetch basic user profile information when they sign in. Automatically adds `profile`, `email`, `phone` and `openid` to the requested scope. Defaults to `true`. ##### accessToken string Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old). ##### providerScope string List of space-delimited, case-sensitive strings representing the requested scope at the social provider. Defaults to the scope configured for the given provider in your Purse Identity Console. > Only for login with social provider. Only for login with social provider. ##### requireRefreshToken boolean If set to `true`, an OAuth 2.0 Refresh Token will be present in the token response. Defaults to `false`. Fetch user basic profile information when they sign in. Adds `profile`, `email`, `phone` and `openid` to the requested scope. > Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ##### returnProviderToken boolean Boolean that specifies whether you should return the provider access token. Defaults to `false`. If set to `true`, you retrieve the provider and provider access token as part of the [authentication result](../docs/models-auth-result.html). Defaults to `code` when `redirectUri` is provided, and to `token` otherwise. This applies to the Login with session flow where a session cookie is provided. In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, `prompt` is handled by the OP and we redirect to the OP because of this. If no value for `prompt` is specified, `none` is the default value for non-orchestrated flows. For orchestrated flows, if no value for `prompt` is specified, users are redirected to the defined Login URL with their orchestration token. This mode is not recommended due to known bugs in Android or Firefox in iOS. Only for login with social provider. Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The `Refresh Token` option must also be selected. ## Response Type: `Promise` ### AuthResult object fields ##### accessToken `string` ##### expiresIn `number` ##### tokenType `string` This is always `Bearer`. ##### refreshToken `string` A refresh token is not present unless you are implementing the refresh token grant. This is only possible when the `offline_access` [scope](../docs/scope.html) is requested. ##### idToken `string` _Claims_ are pieces of information made about a particular subject. For example, ID tokens might contain a claim called `name` that makes the claim that the name of the user authenticating is "Nicole Dubois". ```json { "sub": "987654321", "name": "Nicole Dubois", ... } ``` ##### idTokenPayload `JSON` For a full list of claims, check out the [JWT Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims). ##### code `string` ##### state `string` ##### stepUpToken `string` ##### amr `string` For more on `amr` values, see [here](https://www.rfc-editor.org/rfc/rfc8176.html). ##### providerName `string` This is only relevant for SLO and is not included in the auth response for other flows. ##### providerAccessToken `string` This is only relevant for SLO and is not included in the auth response for other flows. * * * #### ID token payload The possible claims to assert about an authenticated user are outlined in the table below. ##### authType `string` ##### birthdate `string` ##### email `string` ##### emailVerified `boolean` ##### exp `number` ##### familyName `string` Also known as surname or last name. ##### givenName `string` Also known as first name. ##### gender `string` Currently allowed values are `female`, `male` and `other`. ##### iat `number` ##### iss `string` ##### cico `string` ##### locale `string` ##### name `string` ##### newUser `boolean` ##### sub `string` ##### aud `string` ##### picture `string` ##### profile `string` ##### updatedAt `string` ##### auth\_time `number` --- # verifyPhoneNumber URL: /sdk-core/verifyPhoneNumber.html client.verifyPhoneNumber({ [accessToken](#freshAccessToken): string, [phoneNumber](#phoneNumber): string, [verificationCode](#verificationCode): string }) ## About this command Verify the profile phone number with the verification code sent by SMS. > - The profile must have been granted the `full_write` scope at the last authentication. > ## Examples ```javascript client.verifyPhoneNumber({ accessToken: 'eyJ0eXAiOiJKV1QiL...', phoneNumber: '+33606060606', verificationCode: '123456' }) ``` ## Parameters ##### accessToken string The authorization credential [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) used to access the Purse Identity API, less than five minutes old. ##### phoneNumber string The user’s phone number. Both the international format and the national conventions of the account’s country are accepted if configured in account settings. ##### verificationCode string The verification code sent by email or SMS. ## Response Type: `Promise[void]` --- # Obtaining authentication result URL: /sdk-core/guides/authresult.html Purse Identity signup and authentication flows use the [OAuth 2.0](https://tools.ietf.org/html/rfc6749) and [OpenID Connect protocols](https://openid.net/connect/) from a first-party standpoint. All signup, login, and refresh SDK methods lead to a set of JWT tokens, including an ID Token, Access Token and, optionally, a Refresh Token. > The SDK will always emit events that you can listen to using the [on](../on.html) method. The [AuthResult object](../../docs/models-auth-result.html) is the success model that contains the set of tokens or, if implementing an authorization code grant, the resulting code to be exchanged against the token endpoint. Errors are conveyed using the `ErrorResponse` object. In both cases, any passed `state` will be carried throughout the respective flow. There are two main ways of obtaining your authentication result - by [redirecting the user-agent](#using-redirection-for-auth-result) - by [using web messages](#using-web-messages-for-auth-result) ## Using redirection for auth result By default, the SDK redirects the user-agent through Purse Identity’s authorization endpoint, which then redirects the user-agent back to the provided `redirect_uri` (_or the original page in case of an implicit grant_) along with the authentication result. This is the authorization code or set of tokens. When using redirection to obtain an authentication result, we recommended you set `responseType` to `code` and make sure that PKCE is enforced in the client configuration. ```json { "responseType": "code", "redirectUri": "https://www.example.com/login/callback" } ``` > Did you know? The implicit grant will be deprecated in OAuth 2.1. ## Using web messages for auth result Alternatively, you can leverage the `useWebMessage` boolean option in `AuthOptions`. Instead of redirecting user-agents through an authorization endpoint, the web message approach uses a hidden iframe and obtains the authentication result directly from within the webpage. No user-agent redirection is involved in this flow, and the SDK method will conveniently return a `Promise`. Error responses are conveyed in the form of failed promises. When `useWebMessage` is set to `true`, then `responseType` is hardcoded to `code` for increased security purposes. The authorization code will be automatically exchanged against a token set for your convenience, along with any existing PKCE code verifier that might be involved. > Despite there being no user-agent involved, the `redirectUri` parameter is nonetheless still required as per [RFC 6749 Section 1.3.1](https://tools.ietf.org/html/rfc6749#section-1.3.1). You may set any whitelisted URIs as defined in your client configuration. ## `SameSite` cookies The `SameSite` attribute (set on the `Set-Cookie` HTTP response header) enables you to declare if your cookies are restricted to first-party clients or same-site context. At Purse Identity, we set `SameSite` to `Lax` for all browsers except Safari. For Safari, we use `SameSite` = `None`. What’s the difference? `Lax` Cookies are **not** sent on normal cross-site subrequests, but are sent when a user is navigating to the origin site. `None` Cookies are sent in all contexts. > For more details, see [Mozilla’s `SameSite` reference docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite). ### Safari Apple Safari does not currently handle `SameSite=None` HTTPS cookies properly, meaning cookies might not be set for Safari users. > This can be mitigated by using Refresh Tokens to handle long-term sessions. To obtain a Refresh Token, make sure PKCE is enforced in your client configuration, and that the `requireRefreshToken` option is set to `true` **_or_** that your scope includes the `offline_access` value. ---