> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/web-javascript/getting-started/smartauth.md).

# Smart Auth

### **Remote**

Include the **.js** file directly from the CDN:

```html
<script
  src="https://repo.combateafraude.com/identity/<VERSION>/index.umd.js"
  type="text/javascript"
></script>
```

### Current versions

| SDK      | Category | Version                                                                |
| -------- | -------- | ---------------------------------------------------------------------- |
| Identity | Latest   | [`1.1.3`](https://repo.combateafraude.com/identity/1.1.3/index.umd.js) |
| Identity | Stable   | [`1.1.2`](https://repo.combateafraude.com/identity/1.1.2/index.umd.js) |

## **Utilization**

### **Creating an SDK instance**

The SDK's constructor method takes the Identity token as a parameter (see how to get yours [**here**](https://docs.caf.io/caf-docs/user-guide/smart-auth/access-token)). In addition, you can optionally enter the SDK's initialization options.

### **Example using import via CDN:**

```html
<script
  src="https://repo.combateafraude.com/identity/<VERSION>/index.umd.js"
  type="text/javascript"
></script>

[...]

<script>
  const identityToken = "your token";
  const identity = new this["@combateafraude/identity-sdk"].Sdk(identityToken);
</script>
```

{% hint style="info" %}
Starting from version 0.0.33, our options parameters include the personalization of title, subtitle, description and page button text for each page, the background and text color of the modal and the timer position (which can be "UP" or "DOWN").
{% endhint %}

## `Options` parameters:

| **Field**                        | **Type**  | **Required?** | **Description**                                                                                                                                                                                                                                                                                  |
| -------------------------------- | --------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`mobileToken`**                | `string`  | No\*          | A valid [token](https://docs.caf.io/caf-sdk/authentication) for passive proof of life in mobile SDKs.                                                                                                                                                                                            |
| **`throwOnRecall`**              | `boolean` | No            | Indicates whether, when called a second time without the first call having completed, the SDK should throw an error. If not entered or entered **false**, the SDK returns the existing **Promise** without triggering an error. If **true**, the SDK rejects the **Promise** on the second call. |
| **`theme`**                      | object    | No            | To see all the parameters available in the **`theme`** [**click here**](#theme-parameters).                                                                                                                                                                                                      |
| **`smsLabel`**                   | object    | No            | To see all the parameters available in the **`label`** [**click here**](#label-parameters).                                                                                                                                                                                                      |
| **`emailLabel`**                 | object    | No            | To see all the parameters available in the **`label`** [**click here**](#label-parameters).                                                                                                                                                                                                      |
| **`pendingPageSettings`**        | object    | No            | To see all the parameters available in the **`pendingPageSettings`** [**click here**](#pendingpagesettings).                                                                                                                                                                                     |
| **`faceLivenessSettings`**       | object    | No            | Define face authentication styles **`faceLivenessSettings`** [**click here**](#facelivenesssettings-parameters).                                                                                                                                                                                 |
| **`smsSettings`**                | object    | No            | Define sms authentication styles **`smsSettings`** [**click here**](#smssettings-parameters).                                                                                                                                                                                                    |
| **`emailSettings`**              | object    | No            | Define email authentication styles **`emailSettings`** [**click here**](#emailsettings-parameters).                                                                                                                                                                                              |
| **`authIcon`**                   | string    | No            | Icon used at the top of the authentication screens                                                                                                                                                                                                                                               |
| **`enableTimer`**                | boolean   | No            | Enables or disables the timer in case of SMS and E-mail validation                                                                                                                                                                                                                               |
| **`enableLocationRetry`**        | boolean   | No            | Enables retry on geolocation collect, without high accuracy on second try. The default value is false.                                                                                                                                                                                           |
| **`gpsAuthenticationSettings`**  | object    | No            | To see all the parameters available in the **`gpsAuthenticationSettings`** [**click here**](#gpsauthenticationsettings-parameters).                                                                                                                                                              |
| **`successPageDisplayDuration`** | number    | No            | Time in milliseconds that the result page (success or error) remains visible before closing automatically. **Default: 3000**.                                                                                                                                                                    |
| **`timerPosition`**              | string    | No            | Position of timer in case of SMS and E-mail validation (can be "DOWN" or "UP" )                                                                                                                                                                                                                  |
| **`language`**                   | string    | No            | Defines the used language on SDK's texts **`default: pt-BR`**                                                                                                                                                                                                                                    |
| **`metadata`**                   | string    | No            | This field only accepts strings formatted in JSON. Therefore, when submitting data to this field, the string must be in valid JSON format.                                                                                                                                                       |

\*You must inform mobileToken when you are using facial authentication in your policy

{% hint style="info" %}
It is now possible to change the liveness provider used for facial authentication by configuring the mobileToken.\
Contact our support team to choose the best provider for your use case.\
Currently supported liveness providers: **CAF**, **iProov**, **FaceTec**, and **Payface**.
{% endhint %}

## `Theme` parameters:

| **Field**                    | **Type** | **Required?** | **Description**                                           |
| ---------------------------- | -------- | ------------- | --------------------------------------------------------- |
| **`closeButton`**            | string   | No            | Color used in the close button                            |
| **`checkmark`**              | string   | No            | Color used in the checkMark button                        |
| **`loader`**                 | string   | No            | Color used in the loader button                           |
| **`buttonSuccessColor`**     | string   | No            | Color used in the success button                          |
| **`buttonSuccessTextColor`** | string   | No            | Color used in text of the success button                  |
| **`inputSuccessColor`**      | string   | No            | Color used in code input                                  |
| **`buttonFinishColor`**      | string   | No            | Color used in code input                                  |
| **`timerBackgroundColor`**   | string   | No            | Color used in the background of the timer if it is active |
| **`timerColor`**             | string   | No            | Color used in the timer text if it is active              |
| **`modalBackgroundColor`**   | string   | No            | Color used in background of the authentication modal      |
| **`textColor`**              | string   | No            | Color used in text of the authentication modal            |

## `Label` parameters:

| **Field**    | **Type** | **Required?** | **Description**                 |
| ------------ | -------- | ------------- | ------------------------------- |
| **`enable`** | string   | No            | Enables or disables the `label` |
| **`link`**   | string   | No            | Redirection link                |
| **`text`**   | string   | No            | Text used in the `label`        |

## `pendingPageSettings` parameters:

| **Field**               | **Type** | **Required?** | **Description**                                        |
| ----------------------- | -------- | ------------- | ------------------------------------------------------ |
| **`pendingIconSvg`**    | string   | No            | Changes the icon showed when the `PendingPage` is open |
| **`titleText`**         | string   | No            | Title of the `PendingPage`                             |
| **`descriptionText`**   | string   | No            | Description of the `PendingPage`                       |
| **`buttonContentText`** | string   | No            | Text used in the `PendingPage` confirm button          |

## `faceLivenessSettings` parameters:

| **Field**             | **Type** | **Required?** | **Description**                                                         |
| --------------------- | -------- | ------------- | ----------------------------------------------------------------------- |
| **`startButton`**     | `object` | No            | Changes start button **`styles`** [**click here**](#styles-parameters). |
| **`titleText`**       | string   | No            | Title of the `faceLivenessPage`                                         |
| **`subtitleText`**    | string   | No            | Subtitle of the `faceLivenessPage`                                      |
| **`descriptionText`** | string   | No            | Description of the `faceLivenessPage`                                   |

## `gpsAuthenticationSettings` parameters:

| **Field**         | **Type** | **Required?** | **Description**                                                                           |
| ----------------- | -------- | ------------- | ----------------------------------------------------------------------------------------- |
| **`maxAttempts`** | `number` | No            | Maximum number of GPS collection attempts during the authentication flow. **Default: 3**. |

## `smsSettings` parameters:

| **Field**               | **Type** | **Required?** | **Description**                               |
| ----------------------- | -------- | ------------- | --------------------------------------------- |
| **`titleText`**         | string   | No            | Title of the `smsCodePage`                    |
| **`subtitleText`**      | string   | No            | Subtitle of the `smsCodePage`                 |
| **`buttonContentText`** | string   | No            | Text used in the `smsCodePage` confirm button |

## `emailSettings` parameters:

| **Field**               | **Type** | **Required?** | **Description**                                 |
| ----------------------- | -------- | ------------- | ----------------------------------------------- |
| **`titleText`**         | string   | No            | Title of the `emailCodePage`                    |
| **`subtitleText`**      | string   | No            | Subtitle of the `emailCodePage`                 |
| **`buttonContentText`** | string   | No            | Text used in the `emailCodePage` confirm button |

## `styles` parameters:

| **Field**             | **Type** | **Required?** | **Description**                 |
| --------------------- | -------- | ------------- | ------------------------------- |
| **`label`**           | string   | No            | Changes text on button          |
| **`color`**           | string   | No            | Changes color of text on button |
| **`backgroundColor`** | string   | No            | Changes color of background     |
| **`borderRadius`**    | string   | No            | Changes border radius           |
| **`border`**          | string   | No            | Changes border                  |

Exemple:

```javascript
const identityOptions = {
mobileToken: 'seu token mobile',
throwOnRecall: true,
theme: {
    closeButton: '#000037',
    pendingIconSvg:'./example.svg'
    checkmark: "#000037",
    loader: "#000037",
    buttonSuccessColor: "000037",
    buttonSuccessTextColor: "000037",
    inputSuccessColor: "#f6ff00",
    buttonFinishColor: "#00ff0d",
    timerBackgroundColor: "000037",
    timerColor: "white",
    modalBackgroundColor: '000037',
    textColor: '000037'

},
smsLabel: {
    enable: true,
    link: "https://www.google.com/",
    text: "Its just a test SMS",
},
language: "string",
pendingPageSettings: {
        pendingIconSvg:'./example.svg',
        titleText: "Não foi possível realizar a autenticação",
        descriptionText: "Para sua segurança, entre em contato com o suporte para prosseguir",buttonContentText: "Finalizar"
    },
faceLivenessSettings: {
      startButton:{
        label: 'Tirar foto',
        color: "white",// accept hex value too,
        backgroundColor: "#000037",
        border: '1px solid #000037'
      },
        titleText:"insere um titulo",
        subtitleText:"um subtitulo",
        descriptionText:"uma descrição"
},
smsSettings:{
        titleText:"insere um titulo",
        subtitleText:"um subtitulo",
        buttonContentText: 'Validar token sms',
    },
emailSettings:{
        titleText:"insere um titulo",
        subtitleText:"um subtitulo",
        buttonContentText: 'Validar token email',
    },
gpsAuthenticationSettings: {
    maxAttempts: 3,
},
successPageDisplayDuration: 3000,
enableTimer: true,
timerPosition: "UP",
authIcon:  (new Image().src = "./exemple-sdk.png"),
metadata: "{\"teste\":{\"dados\":{\"name\":\"JohnDoe\",\"personId\":\"999.999.999.99\",}}}",
};

const identityToken = 'seu token';

const identity = new IdentitySdk(identityToken, identityOptions);
```

**Calling the SDK:**

To verify a user, use the **`verifyPolicy`** method, available in the SDK instance.

You must enter the user's personId and [**the policy ID**](https://docs.caf.io/caf-docs/user-guide/smart-auth/getting-started#access-policies) to be used.

{% hint style="info" %}
Starting from version 1.0.0, you can use the **personId** parameter as an alternative to CPF for user identification.

* personId can be non-numeric.
* Allowed characters: letters, numbers, and the special characters `@ . _ -` (no spaces).
* Length: between 5 and 254 characters.
* If the personId contains only numbers and the characters `. - /`, these characters will be removed and the value will be interpreted as a document mask.

This allows greater flexibility for user identification in your authentication flows.
{% endhint %}

```javascript
const personId = "User personId";
const policyId = "Policy ID";

const response = await identity.verifyPolicy(personId, policyId);

if (identity.isSdkError(response)) {
  // Error when running the SDK
} else {
  const { isAuthorized, attestation, attemptId } = response;

  if (isAuthorized) {
    // User is authorized
    // Send the attestation to your backend and validate it there
  } else {
    // User is not authorized
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-sdk/web-javascript/getting-started/smartauth.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.