Skip to content

Organization (Legal Person) — Onboarding guide

Date: 2026-07-04. Scope: registering an organization on the eID platform, managing representation rights, using an e-Seal (organization seal), and RP (e-service) side integration. Design rationale: docs/ORG_AUTH_SIGN_PLAN.md; standards: SK ID Solutions SK-CPR-ORG v13.0, ETSI EN 319 412-1/-3/-5.

Core principle (the Estonian model): An organization has NO app account, phone, PIN, or threshold key. Every organization action happens through three mechanisms: 1. Signing in as an organization = a natural person signs in with their own eID, and the RP checks their rights in real time against the representation registry (the right is NOT in the cert — it is in the registry). 2. Signing on behalf of an organization = the representative's PERSONAL PIN2 cert + an onBehalfOf marker on the session (the server has verified the right). 3. e-Seal (seal) = an automatic seal backed by a server-side HSM key, with an NTRMN- cert — non-interactive (invoices, statements, etc., directly from a system).

1. Identifier

Item Value
ETSI identifier NTRMN-<national registration number> (ETSI EN 319 412-1 §5.1.4, NTR semantics)
Cert subject SERIALNUMBER=<registration number>, CN/O=<name>, organizationIdentifier(2.5.4.97)=NTRMN-<number>, C=MN
Issuing CA Gerege Organization Issuing CA (L2) — selected automatically by SubjectTypeForEtsi

2. Registering an organization (operator/admin)

The Organizations tab in the admin console, or the API:

POST /v3/admin/organizations            (org:write)
  {"orgRegister":"1234567","name":"Тест ХХК","nameLatin":"TEST LLC","activate":false}
  • activate:false → created with PENDING status; after verification the admin advances it via the FSM.
  • FSM: PENDING → VERIFIED → ACTIVE → SUSPENDED/REVOKED (can be restored from SUSPENDED; REVOKED is terminal — active seal certs are automatically revoked and placed into OCSP/CRL).
PATCH /v3/admin/organizations/{etsi}    {"status":"ACTIVE"}

3. Representation rights (representation)

Every authorized representative must have their own eID (be enrolled):

POST /v3/admin/organizations/{etsi}/representatives   (org:write)
  {"personEtsi":"PNOMN-…","role":"Гүйцэтгэх захирал","rightType":"ADMIN",
   "source":"MANUAL","evidenceRef":"тушаал №…","validTo":null}
DELETE /v3/admin/organizations/{etsi}/representatives/{id}
  • rightType: ADMIN (created/linked the organization — can add/remove MANAGER signers beneath them) | MANAGER (a signer — cannot add/remove anyone beneath them).
  • source: REGISTRY (from УБЕГ/DAN — future automatic sync) | MANUAL (attested by document).
  • If the term (validTo) has expired, the right has been deactivated, or the organization is not ACTIVE, the right does NOT appear in lookups.

4. RP side integration

4.1 Signing in as an organization

  1. Sign the user in via the usual personal auth (/v3/authentication/...).
  2. Then: 
    GET /v3/organization/representations/etsi/{personEtsi}     (RP auth)
→ {"personEtsi":"PNOMN-…","representations":[
     {"orgEtsi":"NTRMN-…","orgName":"…","rightType":"ADMIN","role":"…", …}]}
  3. Present a "which organization to continue as" choice in the UI, and create the session in the context of the selected organization. Rights can change day to day — check on every session.

4.2 Signing on behalf of an organization

Add onBehalfOf to the sign request: 

POST /v3/signature/notification/etsi/{personEtsi}
  { …, "onBehalfOf":"NTRMN-1234567" }
- The server checks the representation right at the moment the session is created: without the right, 403; for an unidentified (anonymous) user, 403. - The phone confirmation screen shows "You are signing on behalf of X". - The session status (GET /v3/session/{id}) gains an onBehalfOf: {orgEtsi, orgName} block; the signature itself remains the person's PIN2 cert (no crypto change). - Both ADMIN and MANAGER can sign on behalf of the organization on their own (no co-signing requirement on the crypto side); if collecting multiple signatures is required, that is the RP's rule (same as Estonia).

4.3 e-Seal (organization seal)

The RP must have been granted the SEAL permission (in the admin RP registration's permissions, AUTH,SIGN,SEAL); first-party (your own web) is unrestricted.

POST /v3/seal/certificate/{orgEtsi}    — seal key + cert issuance (or via admin:
                                          POST /v3/admin/organizations/{etsi}/seal-certificate)
GET  /v3/seal/certificate/{orgEtsi}    — the active cert (for validation)
POST /v3/seal/{orgEtsi}                — sealing:
  {"digest":"<base64 SHA-256/384/512>"} → {"signature":{"value","signatureAlgorithm"},
                                            "cert":{"value","certificateLevel"},"sealedAt"}
  • Non-interactive, synchronous — no PIN/push (the SK e-Seal model).
  • If the organization is not ACTIVE, or the cert is revoked/superseded, 409 (fail-closed).
  • Cert profile (SK-CPR-ORG): KeyUsage = only nonRepudiation; no EKU; QCStatements = QcCompliance + QcType=eseal; policy QCP-l. When SMARTID_SEAL_QSCD=true (real QSCD/HSM) + QcSSCD, policy QCP-l-qscd, level QSCD.

4.4 Managing signers from the RP side (self-service)

A representative with the ADMIN right can add/remove MANAGER signers for their organization from the RP's UI (the admin console is not required). Every endpoint requires RP auth + the ORG_LINK_WRITE permission; {actingPersonEtsi} must be an ADMIN representative of that organization (otherwise 403). {orgRegister} = the organization's national registration number.

GET    /v3/organization/signers/{orgRegister}/etsi/{actingPersonEtsi}
       → current signers (in verified/pending status)
POST   /v3/organization/signers/{orgRegister}/etsi/{actingPersonEtsi}
       {"signerRegNo":"<РД of the citizen to add>","role":"Нягтлан бодогч"}
       — the added right is ALWAYS MANAGER (rightType is ignored); a sign-push is sent to the citizen to
         request confirmation.
DELETE /v3/organization/signers/{orgRegister}/etsi/{actingPersonEtsi}?signer=<РД>
POST   /v3/organization/signers/{orgRegister}/etsi/{actingPersonEtsi}/resend?signer=<РД>
       — re-sends a sign-push to an unconfirmed signer.

The organization's Latin name (ICAO/latin, the one that goes into the cert) can be edited only by ADMIN:

PUT /v3/organization/name-latin/{orgRegister}/etsi/{actingPersonEtsi}
    {"nameLatin":"TEST LLC"}

РД (signerRegNo) is the registration number — case-insensitive (lookup lowercase); nameLatin is ICAO canonical, so it is stored uppercase (Identifiers).

4.5 Revocation checking

  • OCSP: POST /ocsp — a single endpoint; the responder selects the Personal/Organization CA itself by the issuer hash in the request.
  • CRL: GET /crl (Personal CA), GET /crl/org (Organization CA).
  • Discovery: GET /.well-known/eid — the organization/seal endpoints are listed.

5. Configuration (server)

Env Value
SMARTID_HSMPROXY_ORG_KEY_LABEL HSM key label of the Organization issuing CA (if empty, Personal CA fallback)
SMARTID_HSMPROXY_ORG_ISSUING_CERT Organization issuing CA cert (PEM path)
SMARTID_SEAL_QSCD true = e-Seal leaf key in the HSM (QSCD; QcSSCD+QCP-l-qscd). Requires the hsmproxy CA provider + creds (otherwise fail-fast). false = software seal keys (QUALIFIED). Ceremony: docs/PKI_CA_ONBOARDING.md
SMARTID_SEAL_KEY_PREFIX HSM seal key label prefix (default eseal-; label = prefix + registration code)

6. Audit

Every action goes into audit_events: ORG_REGISTER, ORG_STATUS, ORG_REP_ADD/REMOVE, ORG_REP_LOOKUP (which RP checked whose right), ORG_ONBEHALF (OK/DENIED), SEAL_CERT_ISSUE, ORG_SEAL (OK/DENIED).

7. Limitations / next steps

  • The УБЕГ/DAN legal-entity registry API is not connected — representation is currently sourced from MANUAL (by document); once the API is opened, REGISTRY sync will be added (Phase 0/1).
  • If the org CA is not configured in staging, the seal cert is issued from the Personal CA (caFor fallback) — in production the Organization CA is mandatory (deploy/README.md cutover list).
  • The legal status of the e-Seal (the Mongolian-law equivalent of the eIDAS "electronic seal") is to be clarified with legal counsel (ORG_AUTH_SIGN_PLAN §4).