Skip to content

Cognito Check API & Options

Use this reference to configure @moveris/cognito-check as a Web Component in non-React or mixed frontend environments.

In plain terms

This package is used as <cognito-check>. You pass values through HTML attributes and receive outcomes through DOM events.

Import

import '@moveris/cognito-check';

The import registers the cognito-check custom element globally. You only need to run it once per app.

Usage Model

Render the custom element in your page:

<cognito-check api-key="your-api-key"></cognito-check>

Attributes

Attribute Required Description
api-key Yes Moveris API key. Sent as X-API-Key on verification requests
style No Standard HTML inline style. Controls the widget container's appearance and layout 
<!-- Example: align widget left in a flex layout -->
<cognito-check api-key="your-api-key" style="align-self: flex-start;"></cognito-check>

Events

cognitoSuccess

Fired when the user passes verification.

widget.addEventListener('cognitoSuccess', (e: CustomEvent) => {
  const { outcome, sessionId } = e.detail;
  // outcome: 'pass'
  // sessionId: string -- verify this on your server
});

cognitoError

Fired when verification fails, the user cancels, or the request times out.

widget.addEventListener('cognitoError', (e: CustomEvent) => {
  const { outcome, reason } = e.detail;
  // outcome: 'fail'      -- liveness check completed but verdict was fake
  // outcome: 'cancelled' -- user closed the modal, or request timed out (30s)
  // reason: string       -- human-readable description
});

Framework Examples

Angular

// app.module.ts -- allow custom elements
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import '@moveris/cognito-check';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- signup.component.html -->
<cognito-check
  api-key="your-api-key"
  (cognitoSuccess)="onVerified($event)"
  (cognitoError)="onFailed($event)"
></cognito-check>

// signup.component.ts
onVerified(e: CustomEvent) {
  const { sessionId } = e.detail;
  this.verified = true;
}

onFailed(e: CustomEvent) {
  console.warn(e.detail.reason);
}

Vue 3

// main.ts -- tell Vue to ignore the custom element
import { createApp } from 'vue';
import '@moveris/cognito-check';
import App from './App.vue';

const app = createApp(App);
app.config.compilerOptions.isCustomElement = (tag) => tag === 'cognito-check';
app.mount('#app');

<!-- SignupForm.vue -->
<template>
  <cognito-check
    api-key="your-api-key"
    @cognitoSuccess="onVerified"
    @cognitoError="onFailed"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import '@moveris/cognito-check';

const verified = ref(false);

function onVerified() {
  verified.value = true;
}

function onFailed(e: CustomEvent) {
  console.warn(e.detail.reason);
}
</script>

Svelte

<script>
  import '@moveris/cognito-check';

  let verified = false;

  function onVerified(e) {
    verified = true;
  }

  function onFailed(e) {
    console.warn(e.detail.reason);
  }
</script>

<cognito-check
  api-key="your-api-key"
  on:cognitoSuccess={onVerified}
  on:cognitoError={onFailed}
/>

TypeScript

If you use TypeScript and reference <cognito-check> in JSX or templates, add the element to your project's type declarations:

// global.d.ts
declare global {
  interface HTMLElementTagNameMap {
    'cognito-check': HTMLElement & {
      'api-key': string;
    };
  }
}

Troubleshooting

Symptom Likely Cause Fix
Widget does not render Missing package import Ensure import '@moveris/cognito-check' runs before rendering
Requests fail with 401/403 Invalid or restricted API key Check key validity and tenant permissions
No success callback Listening to wrong event name Use cognitoSuccess and cognitoError exactly
Vue warns about unknown element isCustomElement not configured Add app.config.compilerOptions.isCustomElement for cognito-check
Angular template errors on element Missing CUSTOM_ELEMENTS_SCHEMA Add it to the hosting module's schemas array

Security Notes

  • Treat sessionId as a proof token and validate it server-side before granting access.
  • Do not trust browser-only state for sensitive actions.
  • Never embed production api-key values directly in public HTML; inject them via your build/config pipeline.

Next Steps