Signatures API

Digital signature and certificate endpoints.

List Certificates

Get user's certificates.

GET /api/v1/certificates
Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "cert-uuid",
      "label": "My Work Certificate",
      "type": "ca_issued",
      "status": "active",
      "is_default": true,
      "subject_cn": "John Doe",
      "issuer_cn": "GSign CA",
      "valid_from": "2026-01-01T00:00:00Z",
      "valid_to": "2027-01-01T00:00:00Z",
      "usage_count": 15,
      "last_used_at": "2026-01-24T10:00:00Z",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

Generate Certificate

Generate a new certificate via HSM.

POST /api/v1/certificates/generate
Authorization: Bearer <access_token>

Request

{
  "label": "My New Certificate",
  "common_name": "John Doe",
  "email": "john@example.com",
  "organization": "Example Corp",
  "validity_days": 365,
  "pin": "1234"
}

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "cert-uuid",
    "label": "My New Certificate",
    "type": "self_signed",
    "status": "active",
    "subject_cn": "John Doe",
    "issuer_cn": "GSign HSM CA",
    "valid_from": "2026-01-24T00:00:00Z",
    "valid_to": "2027-01-24T00:00:00Z",
    "serial_number": "123456789",
    "created_at": "2026-01-24T10:00:00Z"
  }
}

Import Certificate

Import an existing certificate.

POST /api/v1/certificates/import
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

Request

Field	Type	Required	Description
file	file	Yes	Certificate file (.p12, .pfx, .pem)
password	string	Yes	Certificate password
label	string	No	Display label
pin	string	Yes	PIN for future use

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "cert-uuid",
    "label": "Imported Certificate",
    "type": "imported",
    "status": "active",
    "subject_cn": "John Doe",
    "issuer_cn": "External CA",
    "valid_from": "2025-01-01T00:00:00Z",
    "valid_to": "2027-01-01T00:00:00Z"
  }
}

Get Certificate

Get certificate details.

GET /api/v1/certificates/:id
Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "cert-uuid",
    "label": "My Certificate",
    "type": "ca_issued",
    "status": "active",
    "is_default": true,
    "subject": {
      "common_name": "John Doe",
      "email": "john@example.com",
      "organization": "Example Corp",
      "country": "MN"
    },
    "issuer": {
      "common_name": "GSign CA",
      "organization": "GSign"
    },
    "serial_number": "123456789",
    "key_type": "RSA",
    "key_size": 2048,
    "valid_from": "2026-01-01T00:00:00Z",
    "valid_to": "2027-01-01T00:00:00Z",
    "usage_count": 15,
    "last_used_at": "2026-01-24T10:00:00Z"
  }
}

Update Certificate

Update certificate metadata.

PUT /api/v1/certificates/:id
Authorization: Bearer <access_token>

Request

{
  "label": "New Label",
  "is_default": true
}

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "cert-uuid",
    "label": "New Label",
    "is_default": true
  }
}

Delete Certificate

Delete a certificate.

DELETE /api/v1/certificates/:id
Authorization: Bearer <access_token>

Request

{
  "pin": "1234"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "message": "Certificate deleted successfully"
  }
}

Sign Document

Sign a document with certificate.

POST /api/v1/certificates/:id/sign
Authorization: Bearer <access_token>

Request

{
  "document_id": "doc-uuid",
  "pin": "1234",
  "reason": "I agree to the terms",
  "location": "Ulaanbaatar, Mongolia"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "signed_document_url": "/api/v1/documents/doc-uuid/download?signed=true",
    "signature": {
      "algorithm": "SHA256withRSA",
      "signed_at": "2026-01-24T10:00:00Z",
      "signer": "John Doe",
      "reason": "I agree to the terms"
    }
  }
}

Validate Certificate

Check certificate validity.

POST /api/v1/certificates/:id/validate
Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "valid": true,
    "expired": false,
    "revoked": false,
    "days_until_expiry": 342,
    "expiry_date": "2027-01-01T00:00:00Z"
  }
}

Certificate Types

Type	Description	Cost
self_signed	For testing	Free
ca_issued	Standard CA	$75
eidas	EU qualified	$250
corporate	Organization	$150

Certificate Status

Status	Description
active	Valid and usable
expired	Past validity date
revoked	Manually revoked
suspended	Temporarily disabled

Signature Types

Type	Description
simple	Draw/type signature
advanced	PKI with certificate
qualified	QES with HSM