Identity Provider (IDP) API

The Identity Provider (IDP) service centralizes user identity management and provides robust secondary authentication layers. It allows organizations to link external user identifiers to a secure, managed identity capable of Multi-Factor Authentication (MFA) via Time-based One-Time Passwords (TOTP) and advanced risk assessment (Sentinel).

Identity Management

Provision External User

Provision a new managed identity within the IDP ecosystem. This creates a security context linked to your platform's internal external_id.

{
  "user": {
    "external_id": "ORG_USR_9921_AFG"
  }
}

{
  "user": {
    "id": "6908bffd...",
    "external_id": "ORG_USR_9921_AFG",
    "status": "active"
  }
}

{
  "error": "User with this external_id already exists for this company"
}

Retrieve Identity Profile

Fetch the security profile for a specific user. This includes authentication capabilities (MFA status), operational status (locked/active), and audit metadata.

{
  "id": "6908...",
  "external_id": "ORG_USR_9921_AFG",
  "status": "active",
  "has_otp": true,
  "has_passkeys": false,
  "is_locked": false,
  "failed_attempts": 0,
  "saas_client_id": "67c9..."
}

Multi-Factor Authentication (MFA)

Configuration of TOTP Secret

Generate a new TOTP secret and QR code payload to enable secondary authentication. Scanning this payload into an authenticator application (e.g., Microsoft/Google Authenticator) completes the setup.

{
  "otp": {
    "issuer_name": "Acme Enterprise",
    "account_name": "alexander@enterprise.com"
  }
}

{
  "user": {
    "external_id": "ORG_USR_9921_AFG",
    "new_otp_secret": "REDACTED_OTP_SECRET",
    "qrcode_payload": "otpauth://totp/Acme+Enterprise:alexander%40enterprise.com?secret=REDACTED_OTP_SECRET&issuer=Acme+Enterprise",
    "is_setup_complete": true
  }
}

Verify Authentication Code

Validate a 6-digit TOTP code (or a one-time backup code) to finalize the authentication process.

{
  "otp": {
    "id": "ORG_USR_9921_AFG",
    "code": "552192"
  }
}

{
  "status": "success",
  "id": "ORG_USR_9921_AFG",
  "message": "OTP verified successfully."
}

{
  "error": "Invalid credentials or access denied"
}

Provision Backup Codes

Generate a collection of single-use backup codes. These allow users to regain access if the primary MFA device is unavailable.

{
  "user": {
    "id": "ORG_USR_9921_AFG",
    "backupCodes": [
      "ABCD-1234",
      "EFGH-5678",
      "..."
    ]
  }
}

Sentinel Risk Assessment

Sentinel provides a sophisticated analytical layer for evaluating authentication risk in real-time.

Analyze Session Integrity (Discover)

Submit session metadata to Sentinel to perform a risk assessment based on behavioral patterns, network reputation, and environmental context.

{
  "sentinel": {
    "id": "6908bffd...",
    "context": {
      "ip": "1.1.1.1",
      "ua": "EnterpriseAgent/1.0"
    }
  }
}

{
  "status": "authorized",
  "risk_score": 0.05,
  "recommendation": "allow"
}

{
  "error": "High risk detection",
  "risk_score": 0.95
}