Sailpoint - BYO IDV

The integration follows a BYO IDV (Bring Your Own Identity Verification) pattern. When a SailPoint workflow determines that identity verification is required, it calls the 1Kosmos IDV API, which sends the user a biometric verification journey.

The user completes document scanning and facial liveness matching on their mobile device. 1Kosmos evaluates the results against the claimed identity and posts a verification outcome back to SailPoint via a callback URL or a separate API call.

A SailPoint workflow then processes the verification result and updates the identity attribute (e.g., idvVerified) and continues with provisioning, access approval, or account recovery accordingly.

Common triggers for this integration include new employee onboarding (confirming identity before provisioning access to critical systems), access requests for sensitive resources or privileged roles, account recovery (replacing helpdesk-based identity verification before password reset), and periodic re-verification of high-risk identities.

The integration supports both asynchronous verification flows initiated from SailPoint and synchronous status queries using the 1Kosmos API.

Prerequisites

• Active 1Kosmos tenant with IDV enabled: Administrator access to the AdminX portal with the Identity Verification capability provisioned. Contact 1kosmos.com/contact if not yet provisioned.

• 1Kosmos API credentials: A 1Kosmos Community API Key and Community ID, available from AdminX → Settings → Community Settings. These are used to authenticate SailPoint's API calls to 1Kosmos.

• SailPoint Identity Security Cloud tenant: ORG_ADMIN access to configure workflows, event triggers, and identity attributes. Access to SailPoint's API with a Personal Access Token or OAuth client credentials.

• SailPoint Workflow capability: Workflow functionality must be enabled on your SailPoint ISC tenant. Contact your SailPoint Customer Success Manager if workflows are not available.

• Identity attribute for IDV status: A custom identity attribute (e.g., idvVerified, type Boolean or String) must be created in SailPoint ISC to store the verification result returned by 1Kosmos.

• User mobile number or email on file: The identity record in SailPoint must have a valid mobile phone number or email address to allow 1Kosmos to deliver the verification journey invitation to the user.

Configuration values

Values to collect from 1Kosmos AdminX for SailPoint:

Values to collect from SailPoint ISC for 1Kosmos callback configuration:

Integration architecture

The integration uses an asynchronous request-callback pattern:

• SailPoint triggers 1Kosmos: A SailPoint workflow fires an HTTP action that calls the 1Kosmos IDV API with the user's identity attributes (name, email, phone). 1Kosmos creates a verification session and returns a session ID and an invitation URL or sends the user a direct mobile notification.

• User completes verification: The user opens the 1Kosmos app or follows the invitation link, scans a government-issued ID document, and completes a facial liveness check. 1Kosmos evaluates the document authenticity and biometric match.

• 1Kosmos posts result to SailPoint: After verification completes, 1Kosmos calls back to a SailPoint event trigger webhook endpoint or the SailPoint REST API, sending the verification outcome (verified/failed), the assurance level achieved (IAL1/IAL2), and metadata such as the verified name and document type.

• SailPoint processes the result: The receiving SailPoint workflow updates the identity's idvVerified attribute via the SailPoint Identities API, then triggers downstream actions: continue provisioning if verified, escalate to manual review if failed, or notify the requestor.

Integration steps

Step 1: Create the IDV status identity attribute in SailPoint ISC

• Log in to SailPoint ISC and navigate to Admin → Identity Profiles → [your profile] → Mappings.

• Create a new custom identity attribute. Recommended name: idvVerified (Boolean) or idvStatus (String, to store values such as "VERIFIED", "FAILED", "PENDING"). Set visibility and editability as appropriate for your governance requirements.

• Save the attribute schema change and republish the identity profile.

Step 2: Generate a SailPoint OAuth client for the 1Kosmos callback

• In SailPoint ISC, navigate to Admin → API Management and create a new OAuth 2.0 client with the idn:identity:update and idn:workflow:execute scopes.

• Save the Client ID and Client Secret. 1Kosmos will use these credentials to authenticate when posting verification results back to SailPoint.

• Provide the SailPoint tenant API base URL, Client ID, and Client Secret to your 1Kosmos representative or configure them in AdminX under the SailPoint callback settings for your IDV tenant.

Step 3: Configure the IDV initiation workflow in SailPoint ISC

• In SailPoint ISC, navigate to Admin → Workflows and create a new workflow.

• Add a trigger for the event that should initiate identity verification (e.g., Identity Created, Access Request Submitted for a sensitive role, or a manual trigger for account recovery).

• Add an HTTP Action node to call the 1Kosmos IDV API. Configure the node with the 1Kosmos IDV session endpoint, API Key, and Community ID. Pass the user's identity attributes (display name, email or phone) in the request body as required by the 1Kosmos IDV API specification.

• Store the session ID returned by 1Kosmos in a workflow variable for correlation when the callback arrives.

Example HTTP action payload to initiate a 1Kosmos IDV session:

POST https://[tenant].1kosmos.net/api/v1/community/[communityId]/idv/session
Authorization: Bearer [API_KEY]
Content-Type: application/json

{
  "user_identifier": "{{identity.email}}",
  "first_name": "{{identity.firstname}}",
  "last_name": "{{identity.lastname}}",
  "phone": "{{identity.phone}}",
  "callback_url": "https://[sailpoint-tenant].api.identitynow.com/beta/trigger-invocations/[trigger-id]/invoke",
  "required_ial": 2,
  "document_types": ["passport", "drivers_license"]

POST https://[tenant].1kosmos.net/api/v1/community/[communityId]/idv/session
Authorization: Bearer [API_KEY]
Content-Type: application/json

{
  "user_identifier": "{{identity.email}}",
  "first_name": "{{identity.firstname}}",
  "last_name": "{{identity.lastname}}",
  "phone": "{{identity.phone}}",
  "callback_url": "https://[sailpoint-tenant].api.identitynow.com/beta/trigger-invocations/[trigger-id]/invoke",
  "required_ial": 2,
  "document_types": ["passport", "drivers_license"]

POST https://[tenant].1kosmos.net/api/v1/community/[communityId]/idv/session
Authorization: Bearer [API_KEY]
Content-Type: application/json

{
  "user_identifier": "{{identity.email}}",
  "first_name": "{{identity.firstname}}",
  "last_name": "{{identity.lastname}}",
  "phone": "{{identity.phone}}",
  "callback_url": "https://[sailpoint-tenant].api.identitynow.com/beta/trigger-invocations/[trigger-id]/invoke",
  "required_ial": 2,
  "document_types": ["passport", "drivers_license"]

Step 4: Configure the IDV result processing workflow in SailPoint ISC

• Create a second SailPoint workflow that receives the 1Kosmos verification result callback. Use a Webhook or HTTP Event Trigger as the entry point.

• Add logic to parse the incoming payload from 1Kosmos and extract the verification status and IAL level.

• Add a SailPoint API Action node to update the identity's idvVerified attribute using the SailPoint Identities API (PATCH /v3/identities/{id}/attributes) or via account attribute update on the authoritative source.

• Add branching logic: if idvStatus == "VERIFIED", continue the original provisioning or access request workflow. If idvStatus == "FAILED", notify the requester and escalate to an admin for manual review.

Example SailPoint API call to update the IDV attribute after receiving a 1Kosmos callback:

PATCH https://[tenant].api.identitynow.com/v3/identities/{{identityId}}
Authorization: Bearer [SAILPOINT_ACCESS_TOKEN]
Content-Type: application/json

[
  {
    "op": "replace",
    "path": "/attributes/idvVerified",
    "value": true
  },
  {
    "op": "replace",
    "path": "/attributes/idvIAL",
    "value": 2
  }
]

PATCH https://[tenant].api.identitynow.com/v3/identities/{{identityId}}
Authorization: Bearer [SAILPOINT_ACCESS_TOKEN]
Content-Type: application/json

[
  {
    "op": "replace",
    "path": "/attributes/idvVerified",
    "value": true
  },
  {
    "op": "replace",
    "path": "/attributes/idvIAL",
    "value": 2
  }
]

PATCH https://[tenant].api.identitynow.com/v3/identities/{{identityId}}
Authorization: Bearer [SAILPOINT_ACCESS_TOKEN]
Content-Type: application/json

[
  {
    "op": "replace",
    "path": "/attributes/idvVerified",
    "value": true
  },
  {
    "op": "replace",
    "path": "/attributes/idvIAL",
    "value": 2
  }
]

Step 5: Test the end-to-end flow

• Trigger the initiating event in SailPoint ISC (e.g., create a test identity or submit a test access request for the protected role).

• Confirm the workflow fires and the 1Kosmos IDV session is created. Check 1Kosmos AdminX → IDV Sessions to verify the session was received.

• Complete the identity verification on a test device: scan a valid ID document and complete the liveness check using the 1Kosmos app or the invitation link.

• Confirm the verification callback is received by the SailPoint result-processing workflow. Check that the identity's idvVerified attribute is updated in SailPoint ISC.

• Verify that downstream provisioning or access approval proceeds (or is denied) according to the configured workflow logic.

Use cases

Attribute mappings

Integration notes

The 1Kosmos IDV API endpoint paths and request/response schemas are specific to your 1Kosmos tenant version.

Confirm the exact endpoint URLs and payload structure with your 1Kosmos representative before building the SailPoint workflow HTTP action nodes. The example payloads in this guide follow the general 1Kosmos API pattern and should be validated against the current AdminX API reference documentation for your tenant.

SailPoint Identity Security Cloud workflows support HTTP action nodes with OAuth 2.0 bearer token authentication, which aligns directly with the 1Kosmos API authentication model. For tenants that require 1Kosmos to write results directly back into SailPoint attributes, a SailPoint OAuth client scoped to idn:identity:update must be provisioned and its credentials shared with 1Kosmos to authorize the inbound callback writes. Organizations that prefer to keep SailPoint as the only writer may configure 1Kosmos to post verification results to an intermediate endpoint or messaging queue, and have a SailPoint workflow poll or subscribe to that queue.

The idvVerified attribute should be treated as a governance-critical data field. Access policies and role assignments that depend on verified identity status should reference this attribute.

Periodically review the idvVerifiedDate attribute to identify identities whose verification has exceeded the organization's re-verification interval and trigger renewal workflows accordingly.