Concepts

Every defined term appears once on this page and is linked throughout the documentation. Read this to picture the object model before touching an API endpoint.

Organization

An institution with one or more applications and explicitly granted capabilities. You are an organization integrating this platform.

An organization has:

Identity: Legal name, registration, and verification status
Applications: One or more independently credentialed workloads (your backend, your mobile app, a partner integration)
Capabilities: Explicit grants such as subscriber:enroll, certificate:request, signature:request
Subscribers: Individuals or entities you have a relationship with and may enroll for certificates

Capabilities are not inferred from role or category; they are explicitly granted. If your organization attempts an operation it has not been granted, the platform returns 403 with the name of the missing capability.

Application

An independently credentialed workload registered with the platform. It may be:

Your organization’s backend API
Your mobile app
A partner system you delegate operations to
An operator console

Every application has:

Credentials: OAuth client credentials and/or mutual TLS certificates for authentication
Webhook endpoints: URLs where the platform sends lifecycle events
Limits and quotas: Rate limits and operational bounds
Environment isolation: Separate credentials and data in sandbox and production

Credentials are rotatable and never define the organization itself. If you rotate an application’s credential, the organization stays unchanged.

Subscriber

A natural person or legal entity whose stable platform identity is independent of the channel that introduced them.

Every subscriber has:

Verified identifiers: National ID number, passport number, or citizenship document number with issuing office
Contacts: Email address(es) and mobile number(s), verified at enrollment
Devices: Registered devices where credentials are installed
Enrollments and certificates: The record of what has been requested and issued
Relationship records: Which organizations may act for them and in what capacity

A subscriber’s identity is established through their verified identifiers. Two records are the same person only if their verified identifiers match. National ID number is authoritative where present; citizenship document number is matched only with its issuing office, because document numbers are not nationally unique (they are issued per district).

Device

A subscriber-controlled installation identified by a device-bound public key and attested properties. It may be:

A mobile phone running ePahichan or an authorized app
A personal computer or laptop
An embedded system or hardware token

The device is an authorization and delivery target, not the subscriber identity itself. A subscriber may register multiple devices and receive different credentials on each.

Enrollment

A policy-bound application for a certificate under one certificate profile. It records:

Requesting organization: Who initiated the enrollment
Subscriber: Who is being enrolled
Identity evidence: The verified identifiers and supporting documents
Certificate request: The class, type, and requested validity period
Statutory application content: The form fields captured at enrollment (name, address, contact, identity evidence, requested use)
Recommendation and approval: Decision records and timing
Subject confirmation: The subscriber’s explicit confirmation of the certificate details before issuance

An enrollment is not a certificate. It is a request that goes through verification, recommendation, approval, confirmation, and issuance before becoming a certificate.

Enrollment lifecycle (simplified):

submitted → verified → recommended → approved → confirmation_required → confirmed → issued
     |                                                                                   |
     └─ information_requested ─────────────────────────────────────────────────────────┘
     |
     └─ rejected (with reasons)

A decision (approval, rejection, or information request) is owed within a statutory window. If the window elapses without a decision, that is recorded as enrollment.decision_overdue — an event that tells your system a response is late, not a state that terminates the enrollment.

An applicant confirmation is mandatory. Before the certificate is issued, they see and must actively confirm the proposed certificate details. This confirmation is recorded as immutable evidence.

Certificate profile

A versioned policy defining:

Subject construction: What name, organization, locality appear in the certificate
Identity requirements: Which verified identifiers are acceptable
Algorithms and key usage: RSA or ECDSA, signature or encryption or both
Validity period: The maximum lifetime the certificate may have
Permitted organizations: Which organizations may request certificates under this profile
Class: Class 1 (email signing only), Class 2 (email and document signing, with optional encryption), or Class 3 (email, documents, authentication)
Lifecycle behavior: Hold periods, activation rules, revocation reasons

Profiles express the class the application form offers. A subscriber’s accepted terms bind them to the uses their class permits.

Certificate

An authoritative X.509 record, chain, serial, status, profile version, and lifecycle history. It binds:

Subject: The name and identity of the holder
Public key: The key used for signing or encryption
Validity period: The issued and expiry dates
Usage: Whether it may be used for signatures, encryption, or both
Status: Issued (on hold or active), suspended, revoked, or expired

A certificate’s status must be checked at the time a signature was made to determine whether the signature was valid. Current status alone is not enough.

Certificate lifecycle:

issued_on_hold → active → suspended → active
      |            |         \→ revoked
      |            +─→ revoked
      +→ withdrawn (hold expired)
active/suspended ──→ expired

Certificates begin on hold. Issuance may complete before the subscriber submits the signed application form. Until it is, the certificate exists but is on hold, and signatures made during a hold are invalid. Receipt of the completed form releases the hold.

Suspension is temporary and statutory. A report of compromise triggers immediate suspension. Suspension has defined time limits: explanation window, maximum duration, and a show-cause period before revocation. A suspension that reaches its statutory maximum is recorded and published.

Revocation is permanent. Once revoked, a certificate may never be reactivated. It is evidence and is never deleted.

Hold periods are published. Every interval during which a certificate was on hold is recorded, so a verifier can determine whether a signature made at a given time was valid.

Credential copy

A record that a given application on a given device holds a copy of a certificate. One certificate may legitimately be held by several applications the subscriber has authorized. All share one certificate and therefore one status — if the certificate is revoked, all copies stop working.

The credential copy inventory is best-effort, not authoritative. It is assembled from what applications report. An application that does not cooperate need not report. Nothing may treat it as a complete account of where a credential exists.

Delivery

A time-limited, attempt-limited authorization to deliver one encrypted credential package to an authenticated subscriber and registered target device.

Delivery lifecycle:

created → authorized → available → retrieved → import_confirmed → retired
                         └→ expired
                         └→ cancelled
                                      └→ retired

A delivery:

Expires after a defined period (e.g., 24 hours) if not retrieved
Has a limited number of retrieval attempts (e.g., 5)
Is bound to one certificate, subscriber, device, and application
Records the retrieved package digest and import confirmation

The platform never holds the credential after delivery. Once the subscriber imports it to their device, the delivery material is destroyed.

Transfer

A record of one credential copy being provisioned to a further application. A subscriber who already holds a credential from your organization may authorize it to be transferred to another authorized application without re-enrolling.

Transfer lifecycle:

requested → relayed → completed
     |         |
     |         └→ refused
     └→ expired

A transfer is refused if:

The certificate is revoked or suspended
The target application is not permitted to receive credentials

A transfer conducted out of band (subscriber authorizes transfer outside this platform) is recorded after the fact.

Signature request

A request for a subscriber to sign content identified only by its hash. The signature request records:

Requesting organization: Who asked for the signature
Subscriber and device: Who signs and using which registered device
Document hash: What is being signed (by its hash only; the platform never holds the document)
Authorization evidence: Whether proof of authorization is required and how it is obtained
Validity window: How long the request remains open
Outcome: Signed, declined, or expired

Signature request lifecycle:

created → presented → authorized → signed → completed
    |          |                        |
    |          └→ declined              └→ failed
    └→ expired

The content itself never enters the platform. Only the hash crosses this interface. Your system holds and displays the document.

A decline is evidence. If the subscriber refuses to sign, that refusal is recorded with the same standing as a signature. It is not the absence of a signature; it is an active decision.

Attestation

Signed evidence that a subscriber authenticated for a particular signature request by a stated method at a stated assurance level. An attestation binds:

Subscriber identity: Who authenticated
Signing eligibility: Whether they are currently permitted to sign
Document hash: What they authenticated to sign
Authentication time: When the authentication occurred
Authentication method and assurance: How they authenticated (e.g., SMS code) and how strongly it was verified
Contact channel: The verified channel through which the authentication challenge was sent

Attestations are issued either by the platform (for signatures requested through this platform) or by an organization holding a delegation certificate (for signatures requested elsewhere).

The attestation is binding. It is signed and embedded in the signature itself, so a verifier can confirm not only that the subscriber possessed the credential, but that they were authenticated at the moment they used it.

Verified contact channel

A contact channel belonging to the subscriber — an email address or mobile number — verified at enrollment.

The contact channel is immutable. A subscriber wanting to change it must go through complete re-enrollment: full identity re-verification, a new certificate, and the old one revoked. This is deliberately heavyweight, because this channel is the strongest credential in the system. It is used for authorization challenges at signing time, so whoever controls it can sign using any copy of the subscriber’s key, even a stolen one.

The contact value is exposed only to the subscriber and their authorized applications. It never appears in a certificate, an attestation, an audit log, or an event. Only an opaque identifier is recorded, so a verifier can confirm the correct channel was used without learning what it is.

Event

A state-change notification emitted by the platform when something happens to a certificate, delivery, enrollment, or other entity.

Events are:

Thin: They carry identifiers and transition details, not personal data or credential material
Signed: Asymmetrically signed so consumers can verify authenticity
Delivered at least once: Consumers must deduplicate by event identifier
Ordered by version: They carry an aggregate version so you can detect and order them

An event is a notification, not data. When you receive a certificate.suspended event, you learn a certificate was suspended, not the full details. You fetch the details by calling the API under your own authorization.

Events are published through webhooks to endpoints you register. Webhook delivery is retried with bounded backoff and is observable in your console.

Audit event

An append-only security record capturing:

Actor: Who performed the action
Action: What was done
Target: What was changed
Outcome: Did it succeed or fail
Time: When it happened
Request correlation: Which API request caused it (if any)
Integrity link: Previous audit event hash, so any tampering is detectable

Audit records are the evidence you rely on in a dispute or forensic investigation. They are immutable, timestamped, and carry cryptographic integrity proof.

Relationships and ownership

An organization has applications. Each application has independent credentials.
An organization has a relationship with subscribers. A subscriber may have relationships with many organizations.
A subscriber has devices. Each device may receive credentials.
An enrollment becomes a certificate. One certificate belongs to one subscriber and one profile version.
A certificate has multiple credential copies. Each copy records which application on which device holds it.
A delivery is bound to one certificate and one target device/application. The platform never holds the credential after delivery.
An event captures one state transition. Events are causally linked through aggregate version.

See Errors for what goes wrong and how to resolve it, Events for the full catalogue of state changes, and the API Reference for every operation and schema.