Mobile-ID Sign · INTEGRATION & DOCUMENTATION

Trusted SIC — Authorization and hash signing

An edited guide to Compact 1.7.261001 with migration, operation sources and contract limits.

Integration journeys Watch Viewer actions

Coverage and integration prerequisites

Source documentation, contract confirmation, sandbox testing and production acceptance are separate stages. Website version changes do not advance readiness.

Review coverage for each operation

Per-operation readiness
Operation	Documentation	Contract	Sandbox
`POST /v2/auth/login`	Selected fields	Deployment not confirmed	Not tested
`POST /v2/auth/revoke`	Selected fields	Deployment not confirmed	Not tested
`POST /v2/credentials/issue`	Selected fields	Deployment not confirmed	Not tested
`POST /v2/credentials/list`	Selected fields	Deployment not confirmed	Not tested
`POST /v2/credentials/info`	Selected fields	Deployment not confirmed	Not tested
`POST /v2/credentials/authorize`	Selected fields	Deployment not confirmed	Not tested
`POST /v2/signatures/signHash`	Selected fields	Deployment not confirmed	Not tested
`POST /v2/owner/management`	Selected fields	Deployment not confirmed	Not tested

Download scope-specific OpenAPI · Download documentary Postman

Compact scope

Source: Trusted SIC 1.7.261001, “Compact document”. The catalog has 8 REST operations, 3 views, 3 redirect types and 4 callback types. OpenAPI contains selected fields, not complete schemas or an accepted production contract.

OpenAPI JSON OpenAPI YAML Postman Environment

From credential to a validated document

Select a credential and inspect authorization requirements
Generate digests from the exact document revision
authorize: Receive a view token, not a signature
User confirms; backend receives SAD under the contract
signHash: Receive signature data or a tracking identifier
Assemble → validate → store document and evidence

202 Accepted at authorize acknowledges acceptance only. Passkey is an authentication/authorization mechanism in the described journey; it is not a certificate or a digital signature.

Migration from 1.7.260928

SIC migration
Operation	New document	Action
/v2/auth/login, /v2/auth/revoke	Present in Compact	Add catalog and selected fields; no secret fixture.
/v2/credentials/issue, list, info, authorize	Present in Compact	Reconcile schemas, modes and namespaces against the new version.
/v2/signatures/signHash, /v2/owner/management	Present in Compact	Separate authorization, signing and document completion.
providers / package / issueCheck / authorizeCheck / signPolling / history	Not described in Compact	Retain 1.7.260928 separately; do not infer removal.

Read SIC 1.7.260928 documentation

Source-based API Reference

POST/v2/auth/login

Authenticate application

Source documented · Deployment contract unconfirmed · Sandbox not tested

Source: Trusted SIC 1.7.261001 (Compact document) · PDF 6 · selected-fields

Prerequisites: Agree deployment scope, authentication and permissions with Mobile-ID. Keep tokens and signing data on the backend; do not execute from this demo page.

Source authentication: Basic

Input — Documented fields

Content-Type: application/json

Fields edited from the source
Field	Type	Presence	Meaning and limits
`refresh_token`	string	Conditional	Conditional refresh credential; Basic versus refresh selection needs confirmation.
`rememberMe`	string	Optional	Source table uses String; the example uses a Boolean.

HTTP 200

Fields edited from the source
Field	Type	Presence	Meaning and limits
`access_token`	string	Required	Application access token; store on the backend.
`refresh_token`	string	Optional	Refresh token.
`expires_in`	integer	Optional	Access-token expiry value.

Items to confirm: SIC12-LOGIN

POST/v2/auth/revoke

Revoke an application token

Source documented · Deployment contract unconfirmed · Sandbox not tested

Source: Trusted SIC 1.7.261001 (Compact document) · PDF 8 · selected-fields

Prerequisites: Agree deployment scope, authentication and permissions with Mobile-ID. Keep tokens and signing data on the backend; do not execute from this demo page.

Source authentication: Bearer

Input — Documented fields

Content-Type: application/json

Fields edited from the source
Field	Type	Presence	Meaning and limits
`token`	string	Required	Token to revoke.
`token_type_hint`	string	Optional	Token-type hint.

POST/v2/credentials/issue

Issue a credential

Source documented · Deployment contract unconfirmed · Sandbox not tested

Source: Trusted SIC 1.7.261001 (Compact document) · PDF 9 · selected-fields

Prerequisites: Agree deployment scope, authentication and permissions with Mobile-ID. Keep tokens and signing data on the backend; do not execute from this demo page.

Source authentication: Bearer

Input — Documented fields

Content-Type: application/json

Fields edited from the source
Field	Type	Presence	Meaning and limits
`alias`	string	Optional	Optional alias.
`citizenId`	string	Conditional	Required conditionally for synchronous issuance; mode mapping is contradictory.
`packageId`	string	Conditional	Required conditionally for synchronous issuance.
`operationMode`	string · S, A	Optional	Issue table: S asynchronous / A synchronous; response tables conflict.
`sharedMode`	string	Optional	Sharing model from the agreed configuration.
`SCAL`	string · 1, 2	Optional	Source binding level; not a certification claim.
`agreementUUID`	string	Optional	Caller agreement data.
`view`	object	Optional
`view.lang`	string · VI, EN	Optional	UI language.
`view.expiresIn`	integer	Optional	Unit is unresolved in the source; do not infer a duration.
`view.callbackUrl`	string	Optional	Backend result callback URL.
`view.redirectUrl`	string	Optional	Browser redirect URL; not proof of completion.
`view.fontSize`	string	Optional	View font size.
`view.templateUiId`	string	Optional	UI template identifier.

HTTP default

Fields edited from the source
Field	Type	Presence	Meaning and limits
`token`	string	Conditional	View token when a UI is used; response conditions need confirmation.

Items to confirm: SIC12-MODE, SIC12-VIEW

POST/v2/credentials/list

List credentials for an owner

Source documented · Deployment contract unconfirmed · Sandbox not tested

Source: Trusted SIC 1.7.261001 (Compact document) · PDF 13 · selected-fields

Prerequisites: Agree deployment scope, authentication and permissions with Mobile-ID. Keep tokens and signing data on the backend; do not execute from this demo page.

Source authentication: Bearer

Parameters

Operation parameters
Name	In	Required	Type
x-page-no	header	No	string
x-records-per-page	header	No	string

Input — Documented fields

Content-Type: application/json

Fields edited from the source
Field	Type	Presence	Meaning and limits
`userID`	string	Required	Identity identifier of the credential owner.
`credentialInfo`	boolean	Optional	Include credential information.
`certificates`	string · none, single, chain	Optional	Certificate chain selection.
`certInfo`	boolean	Optional	Include certificate fields.
`authInfo`	boolean	Optional	Include authorization mechanism information.
`onlyValid`	boolean	Optional	Filter usable credentials; not a signature validation result.
`lang`	string · VI, EN	Optional	Response language.

HTTP 200

Fields edited from the source
Field	Type	Presence	Meaning and limits
`credentialIDs`	array	Required	Credential identifiers.
`credentialInfos`	array	Conditional	Conditional credential information objects; partial schema.

Synthetic example — No API call

{
  "userID": "DEMO-OWNER",
  "certificates": "single",
  "onlyValid": true
}

Items to confirm: SIC12-NAMESPACE

POST/v2/credentials/info

Inspect a credential before authorization

Source documented · Deployment contract unconfirmed · Sandbox not tested

Source: Trusted SIC 1.7.261001 (Compact document) · PDF 18 · selected-fields

Prerequisites: Agree deployment scope, authentication and permissions with Mobile-ID. Keep tokens and signing data on the backend; do not execute from this demo page.

Source authentication: Bearer

Input — Documented fields

Content-Type: application/json

Fields edited from the source
Field	Type	Presence	Meaning and limits
`credentialID`	string	Required	Credential identifier; keep distinct from a certificate and a transaction.
`certificates`	string · none, single, chain	Optional	Certificate chain selection.
`certInfo`	boolean	Optional	Include certificate fields.
`authInfo`	boolean	Optional	Include authorization mechanism.
`lang`	string	Optional	Response language.

HTTP 200

Fields edited from the source
Field	Type	Presence	Meaning and limits
`multisign`	string	Optional	Maximum signatures: Source table uses String while an example uses a number.
`SCAL`	string · 1, 2	Optional	Hash/SAD binding level.

Synthetic example — No API call

{
  "credentialID": "DEMO-CREDENTIAL",
  "certInfo": true
}

Items to confirm: SIC12-MULTISIGN

POST/v2/credentials/authorize

Authorize the exact digests

Source documented · Deployment contract unconfirmed · Sandbox not tested

Source: Trusted SIC 1.7.261001 (Compact document) · PDF 22 · selected-fields

Prerequisites: Agree deployment scope, authentication and permissions with Mobile-ID. Keep tokens and signing data on the backend; do not execute from this demo page.

Source authentication: Bearer

Input — Documented fields

Content-Type: application/json

Fields edited from the source
Field	Type	Presence	Meaning and limits
`credentialID`	string	Required	Credential identifier; keep distinct from a certificate and a transaction.
`numSignatures`	integer	Required	Number of signatures requested; no unpublished limit inferred.
`documentDigests`	object	Required	Digests to bind to authorization.
`documentDigests.hashes`	array	Required	Base64 digests bound to authorization.
`documentDigests.hashAlgorithmOID`	string	Required	Digest algorithm OID; agree with the signing service.
`description`	string	Optional	Human-readable transaction description.
`agreementUUID`	string	Optional	Caller agreement data.
`username`	string	Optional	Management-session username.
`clientInfo`	object	Optional
`clientInfo.application`	string	Optional	Application name.
`view`	object	Optional
`view.lang`	string · VI, EN	Optional	UI language.
`view.expiresIn`	integer	Optional	Unit is unresolved in the source; do not infer a duration.
`view.callbackUrl`	string	Optional	Backend result callback URL.
`view.redirectUrl`	string	Optional	Browser redirect URL; not proof of completion.
`view.fontSize`	string	Optional	View font size.
`view.templateUiId`	string	Optional	UI template identifier.

HTTP 202

Fields edited from the source
Field	Type	Presence	Meaning and limits
`token`	string	Required	Token used to open authorization view. This is not a SAD.

Synthetic example — No API call

{
  "credentialID": "DEMO-CREDENTIAL",
  "numSignatures": 1,
  "documentDigests": {
    "hashes": [
      "ypeBEsobvcr6wjGzmiPcTaeG7/gUfE5yuYB3ha/uSLs="
    ],
    "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1"
  }
}

Items to confirm: SIC12-VIEW, SIC12-EXPIRES, SIC12-SAD

POST/v2/signatures/signHash

Sign digests with valid authorization

Source documented · Deployment contract unconfirmed · Sandbox not tested

Source: Trusted SIC 1.7.261001 (Compact document) · PDF 24 · selected-fields

Prerequisites: Agree deployment scope, authentication and permissions with Mobile-ID. Keep tokens and signing data on the backend; do not execute from this demo page.

Source authentication: Bearer

Input — Documented fields

Content-Type: application/json

Fields edited from the source
Field	Type	Presence	Meaning and limits
`credentialID`	string	Required	Credential identifier; keep distinct from a certificate and a transaction.
`SAD`	string	Required	Signature Activation Data obtained after authorization; keep on the backend.
`hashes`	array	Required	Base64 digests to sign; must match authorized input.
`hashAlgorithmOID`	string	Required	Digest algorithm OID.
`signAlgo`	string	Required	Signing algorithm identifier required by the table but missing in the source example.
`operationMode`	string · A, S	Optional	Sign table: A asynchronous / S synchronous; distinguish issue mapping.
`validityUeriod`	integer	Optional	Source spelling, validity in milliseconds. Do not silently rename.
`responseUri`	string	Optional	Callback URI described by the signing operation.

HTTP default

Fields edited from the source
Field	Type	Presence	Meaning and limits
`signatures`	array	Conditional	Signature data; assembling a document is a separate step.
`responseID`	string	Conditional	Asynchronous response identifier; not interchangeable with requestID.

Items to confirm: SIC12-SIGNALGO, SIC12-SPELLING, SIC12-POLLING

POST/v2/owner/management

Open owner management

Source documented · Deployment contract unconfirmed · Sandbox not tested

Source: Trusted SIC 1.7.261001 (Compact document) · PDF 26 · selected-fields

Prerequisites: Agree deployment scope, authentication and permissions with Mobile-ID. Keep tokens and signing data on the backend; do not execute from this demo page.

Source authentication: Bearer

Input — Documented fields

Content-Type: application/json

Fields edited from the source
Field	Type	Presence	Meaning and limits
`username`	string	Optional	Username for the management session.
`view`	object	Optional
`view.lang`	string · VI, EN	Optional	UI language.
`view.expiresIn`	integer	Optional	Unit is unresolved in the source; do not infer a duration.
`view.callbackUrl`	string	Optional	Backend result callback URL.
`view.redirectUrl`	string	Optional	Browser redirect URL; not proof of completion.
`view.fontSize`	string	Optional	View font size.
`view.templateUiId`	string	Optional	UI template identifier.

HTTP 200

Fields edited from the source
Field	Type	Presence	Meaning and limits
`token`	string	Required	Management view token.
`expires_in`	integer	Required	Token expiry value.

Items to confirm: SIC12-VIEW, SIC12-EXPIRES

Catalog and coverage

All 8 REST operations, partial field schemas; 3 views, 3 redirects and 4 callbacks documented separately.

Operations in the Specification
Method	Path	Coverage	PDF
POST	`/v2/auth/login`	selected-fields	6
POST	`/v2/auth/revoke`	selected-fields	8
POST	`/v2/credentials/issue`	selected-fields	9
POST	`/v2/credentials/list`	selected-fields	13
POST	`/v2/credentials/info`	selected-fields	18
POST	`/v2/credentials/authorize`	selected-fields	22
POST	`/v2/signatures/signHash`	selected-fields	24
POST	`/v2/owner/management`	selected-fields	26

Views, redirects and callbacks

Result channels
Channel	Meaning	Source
GET /view/authorize/{token}	Authorization view	SIC §2.2.1
GET /view/manage/{token}	Management view	SIC §2.2.2
GET /view/certificate/{token}	Certificate view	SIC §2.2.3
Redirect result={base64}	3 types: Authorization, management, issuance. Base64 encoding does not authenticate the sender.	SIC §4
Callback → backend	4 types: Authorization, management, issuance, signing. Reconcile fields and states per type.	SIC §5

Authenticate callback origin under the agreed contract, persist before acknowledgement, deduplicate and reconcile missing/out-of-order delivery. A browser redirect is not proof of completed signing. Compact does not justify inventing a signature header, retry schedule or polling endpoint.

Items to settle before integration

SIC12-MODE · SIC §3.1.3 và §3.1.7

Issue S/A mapping contradicts signHash and issue response tables.

Do not prescribe a production mode.

SIC12-NAMESPACE · SIC §3.1.4

/v2 catalog differs from /csc/v2 examples.

Retain catalog paths with an issue; confirm base URL.

SIC12-SIGNALGO · SIC §3.1.7

SignAlgo is mandatory but absent in the example.

Do not publish a fabricated complete signHash fixture.

SIC12-SAD · SIC §3.1.7, §4.1, §5.1

SAD is expanded with two terms.

Keep SAD identifier; settle its definition.

SIC12-EXPIRES · SIC view parameters, callbacks

ExpiresIn units conflict; examples also use expires_in.

Do not rename fields or infer expiry duration.

SIC12-MULTISIGN · SIC §3.1.5

Multisign is String in the table and numeric in examples.

Schema retains table type and the issue.

SIC12-SPELLING · SIC §3.1.7

Source uses validityUeriod.

Retain source identifier; do not silently correct API spelling.

SIC12-VIEW · SIC §3.1.6 và sơ đồ Viewer

202 authorize describes token; flow has token and viewURL.

Token is not SAD; confirm the UI URL.

SIC12-POLLING · SIC Compact, lịch sử V11

Compact does not describe polling/history/providers/packages.

Keep older docs separately; absence does not mean removal.

SIC12-CALLBACK · SIC §§4–5

Callbacks have inconsistent JSON, field names and code/status.

Do not publish invalid source payloads as runnable examples.

Compare with Viewer actions

Watch the appropriate route, read outcomes and omissions, then consult the operation. Videos do not replace contracts or validation reports.

Watch seven Viewer/VNeID recordings

Application authentication and tracing

§3.1.1, PDF 6–7 describes Basic login, access_token for subsequent requests, response x-billcode-id and expires_in in seconds. Basic/refresh_token alternatives and rememberMe typing remain subject to source inconsistencies.

Application credentials are handled on the backend; application login is not signing consent or SAD.

Trusted SIC — Authorization and hash signing

Coverage and integration prerequisites

Compact scope

From credential to a validated document

Migration from 1.7.260928

Source-based API Reference

Input — Documented fields

HTTP 200

Input — Documented fields

Input — Documented fields

HTTP default

Parameters

Input — Documented fields

HTTP 200

Input — Documented fields

HTTP 200

Input — Documented fields

HTTP 202

Input — Documented fields

HTTP default

Input — Documented fields

HTTP 200

Catalog and coverage

Views, redirects and callbacks

Items to settle before integration

SIC12-MODE · SIC §3.1.3 và §3.1.7

SIC12-NAMESPACE · SIC §3.1.4

SIC12-SIGNALGO · SIC §3.1.7

SIC12-SAD · SIC §3.1.7, §4.1, §5.1

SIC12-EXPIRES · SIC view parameters, callbacks

SIC12-MULTISIGN · SIC §3.1.5

SIC12-SPELLING · SIC §3.1.7

SIC12-VIEW · SIC §3.1.6 và sơ đồ Viewer

SIC12-POLLING · SIC Compact, lịch sử V11

SIC12-CALLBACK · SIC §§4–5

SIC12-LOGIN · SIC §3.1.1

Compare with Viewer actions

Application authentication and tracing