Deep Link Protocol

Complete specification for securesign:// signing handoff.

URL Scheme

Mobile browsers and desktop browsers use the same scheme. On Android/iOS it opens SecureSign Mobile App; on Windows/Linux/macOS it opens SecureSign Desktop Software.

securesign://sign

Query Parameters

Parameter	Required	Description
requestId	Yes	Unique request UUID (correlate callback)
hashBase64	Yes*	Base64-encoded document hash
hashAlgo	Yes	SHA256 \| SHA384 \| SHA512
documentType	Yes	hash \| pdf \| xml
documentBase64	For pdf/xml	Base64 document when not hash-only
callbackUrl	Yes	URL-encoded HTTPS or app scheme return URL
apiKey	Yes	SecureSign API key
certSerial	No	Filter certificate by serial (hex)

Success Callback

SecureSign App redirects to callbackUrl with signed payload as query param ss_result (base64 JSON) or POST body for app schemes:

https://portal.example.gov.in/sign/callback?ss_result=eyJyZXF1ZXN0SWQiOi4uLn0=

{"requestId":"a1b2","success":true,"signatureBase64":"MEUCIQD...","certificate":{"subjectCN":"Rajesh Kumar","serialNumber":"4A3B2C1D","validTo":"2027-01-01"},"signedAt":"2026-06-22T10:30:00Z"}

Error Callbacks

On failure or cancellation, success is false and error contains a code:

error code	Meaning	Portal action
`SS_SIGN_CANCELLED`	User cancelled signing	Allow retry
`SS_PIN_INVALID`	Wrong PIN	Show remaining attempts if provided
`SS_PIN_BLOCKED`	Token blocked	Direct user to unlock token
`SS_TOKEN_NOT_FOUND`	No DSC token connected	Prompt to connect token
`SS_APP_NOT_INSTALLED`	SecureSign App missing	Show install link from Admin Console
`SS_DOMAIN_NOT_ALLOWED`	Callback origin not whitelisted	Fix domain whitelist config

{"requestId":"a1b2","success":false,"error":"SS_SIGN_CANCELLED","message":"User cancelled signing"}

Universal Links (iOS)

Production iOS integrations may use universal links instead of custom scheme:

Host apple-app-site-association at https://yourdomain.com/.well-known/apple-app-site-association
Register domain in Admin Console → Domain Whitelist
Use https://sign.securesign.toolsbots.com/open?... with same query parameters as securesign://sign

{
  "applinks": {
    "apps": [],
    "details": [{ "appID": "TEAMID.com.toolsbots.securesign", "paths": ["/open", "/open/*"] }]
  }
}