Authentication

Full reference for PIN verification, session management, biometric workflows, and API key authentication.

All features supported

Every authentication capability listed below is implemented and working. Your portal never receives the raw PIN — PIN entry occurs only inside SecureSign Mobile App or Desktop Software.

Overview

SecureSign uses a two-layer authentication model:

Portal layer — API key (ss_live_ / ss_test_) and domain whitelist validate your server-to-server calls.
Token layer — DSC token PIN (and optional device biometric on mobile) validates the end user before private-key operations.

Private keys never leave the token. PINs are never transmitted to your portal or the SecureSign REST API.

Platform Support

Feature	Mobile App	Desktop Software	REST API
PIN Verification	Supported	Supported	— (product UI only)
PIN Change	Product settings	Product settings	—
PIN Retry Counter	Shown in UI	Shown in UI	—
PIN Status Check	Supported	Supported	—
Unlock Token (PUK)	Vendor-dependent	Vendor-dependent	—
Biometric + PIN	Supported	—	—
Session Authentication	Supported	Supported	POST /auth/session
Auto Logout	Idle timeout	Idle timeout	Session expiry
Multi-Factor Auth	API key + PIN	API key + PIN	POST /auth/validate

PIN Workflow

When a sign request requires token access, SecureSign prompts the user for PIN inside the product:

Portal initiates sign via securesign://sign deep link or REST API orchestration.
SecureSign detects token and shows PIN entry screen.
On success, signing proceeds; PIN session may be cached for batch operations.
On failure, retry counter decrements; after max retries token is blocked.

PIN never leaves the product

Do not build PIN input fields in your portal. Collecting DSC PINs in a web form violates security best practice and is not supported.

PIN status values

Status	Description
`ACTIVE`	PIN accepted; signing allowed
`INVALID`	Wrong PIN; retries remaining shown
`BLOCKED`	Max retries exceeded; PUK unlock required
`SESSION_ACTIVE`	PIN verified; session cached for batch signing

Session & MFA

Session authentication — after first successful PIN entry, subsequent signs in the same session skip PIN re-entry until idle timeout (default 15 minutes, configurable in product settings).

Biometric + PIN (Mobile App) — optional device fingerprint/face unlock before PIN screen for faster repeat signing.

Multi-factor — every signing flow requires both a valid API key (portal identity) and token PIN (user identity).

API Authentication

Server-side calls use Bearer token or header:

Authorization: Bearer ss_live_abc123xyz
// or
X-SecureSign-Api-Key: ss_live_abc123xyz

Validate key and domain before initiating signing:

Endpoint	Purpose
`POST /auth/validate`	Verify API key + whitelisted origin
`POST /auth/session`	Create server-side signing session for multi-step workflows

Examples

curl -X POST https://api.securesign.toolsbots.com/v1/auth/validate \
  -H 'Authorization: Bearer ss_live_abc123xyz' \
  -H 'Content-Type: application/json' \
  -d '{"origin":"https://portal.example.gov.in","platform":"web"}'

const { sessionId, deepLink } = await fetch('https://api.securesign.toolsbots.com/v1/auth/session', {
  method: 'POST',
  headers: { Authorization: 'Bearer ss_live_abc123xyz', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    requestId,
    documentType: 'hash',
    hashBase64,
    callbackUrl
  })
}).then(r => r.json());

// Your portal never collects PIN
// SecureSign Mobile App or Desktop Software handles it
// You receive only signatureBase64 + certificate in callback

Response

POST /auth/validate

{"success":true,"tenantId":"org_9f2a","allowed":true,"rateLimit":{"rpm":120}}

POST /auth/session

{"sessionId":"sess_7x9y","expiresAt":"2026-06-22T11:00:00Z","deepLink":"securesign://sign?requestId=a1b2c3d4&..."}

Errors

Code	Cause	Resolution
`SS_PIN_INVALID`	Incorrect PIN	User retries; show remaining attempts
`SS_PIN_BLOCKED`	Token blocked after max retries	PUK unlock via product settings or CA
`SS_API_KEY_INVALID`	Invalid or revoked API key	Check Admin Console key status
`SS_DOMAIN_NOT_ALLOWED`	Origin not whitelisted	Add domain in Admin Console
`SS_SESSION_EXPIRED`	Signing session timed out	Re-initiate sign flow
`SS_SIGN_CANCELLED`	User cancelled PIN entry	Allow user to retry

See also Authentication API and API Keys.