Skip to content

Cybersign Sponsored Onboarding & Signing API (1.1.0)

API endpoints for Cybersign's sponsored user onboarding flow, including authentication, data enrichment, phone verification, KYC status check, document signing preparation (upload/download URLs), certificate management, and document signing.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Mock server

https://docs.cybersign.gt/_mock/openapi/

Production Server

https://api.cybersign.com/v1/

Authentication

Operations related to user signup initiation and login.

Operations

Onboarding

Operations related to the user onboarding process after initial login, including data submission, phone verification, and status checks.

Operations

Documents

Operations related to preparing documents for signing (upload/download) and performing the signature.

Operations

Generate Pre-signed Upload URL

Request

Generates a pre-signed URL suitable for uploading a document directly to Cybersign's secure storage (e.g., S3). The URL expiry depends on the selected file tier.

Security
user_bearer_auth
Bodyapplication/jsonrequired
file_tierstringrequired

Determines the expiry time of the generated pre-signed URL based on expected file size:

  • tier-1: Up to 20MB (7 min expiry)
  • tier-2: Up to 40MB (14 min expiry)
  • tier-3: Up to 80MB (28 min expiry)
  • tier-4: Up to 100MB (35 min expiry)
  • tier-5: Up to 120MB (42 min expiry)
Enum"tier-1""tier-2""tier-3""tier-4""tier-5"
Example: "tier-1"
file_namestringrequired

The intended filename for the document being uploaded (e.g., 'contrato-laboral.pdf'). Used to construct the storage path.

Example: "documento.pdf"
curl -i -X POST \
  https://docs.cybersign.gt/_mock/openapi/documents/upload-url \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "file_tier": "tier-1",
    "file_name": "documento.pdf"
  }'

Responses

Pre-signed URL and associated data generated successfully.

Bodyapplication/json
urlstring(url)required

The base URL endpoint to which the upload request should be sent.

Example: "https://your-bucket-name.s3.your-region.amazonaws.com/"
fieldsobjectrequired

Key-value pairs that must be included as form fields in the upload request (e.g., multipart/form-data).

fields.​keystringrequired

The full path/key where the object will be stored in the bucket.

Example: "user-uuid/onboarding-ulid/documento.pdf"
fields.​x-amz-algorithmstringrequired
Example: "AWS4-HMAC-SHA256"
fields.​x-amz-credentialstringrequired
Example: "AKIAEXAMPLE/20240101/us-east-1/s3/aws4_request"
fields.​x-amz-datestringrequired
Example: "20240101T120000Z"
fields.​policystringrequired

Base64-encoded policy document governing the upload permissions.

Example: "eyJleHBpcmF0aW9uIjoiMjAyNC0wMS0wMVQxMjowNzowMFoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJ5b3VyLWJ1Y2tldC1uYW1lIn0seyJrZXkiOiJ1c2VyLXV1aWQvb25ib2FyZGluZy11bGlkL2RvY3VtZW50by5wZGYifV19"
fields.​x-amz-signaturestringrequired

The calculated signature for the request.

Example: "a1b2c3d4e5f6..."
doc_ulidstring(ulid)required

A unique ULID generated by Cybersign to identify this specific document upload instance.

Example: "01JE9KCR0H22PDY9C1GYZABCDE"
doc_pathstringrequired

The storage path/key assigned to this document. Matches the 'key' field within 'fields'.

Example: "user-uuid/onboarding-ulid/documento.pdf"
Response
application/json
{
  "url": "https://your-bucket-name.s3.your-region.amazonaws.com/",
  "fields": {
    "key": "user-uuid/onboarding-ulid/documento.pdf",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "AKIAEXAMPLE/20240101/us-east-1/s3/aws4_request",
    "x-amz-date": "20240101T120000Z",
    "policy": "eyJleHBpcmF0aW9uIjoiMjAyNC0wMS0wMVQxMjowNzowMFoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJ5b3VyLWJ1Y2tldC1uYW1lIn0seyJrZXkiOiJ1c2VyLXV1aWQvb25ib2FyZGluZy11bGlkL2RvY3VtZW50by5wZGYifV19",
    "x-amz-signature": "a1b2c3d4e5f6..."
  },
  "doc_ulid": "01JE9KCR0H22PDY9C1GYZABCDE",
  "doc_path": "user-uuid/onboarding-ulid/documento.pdf"
}

Generate Pre-signed Download URL

Request

Generates a pre-signed URL for securely downloading a previously signed document. The URL has a short expiry time (e.g., 5 minutes) and is single-use.

Security
user_bearer_auth
Query
document-pathstringrequired

The storage path/key of the signed document to download (obtained previously, e.g., from upload response or signing confirmation).

Example: document-path=user-uuid/onboarding-ulid/document-name.pdf
curl -i -X GET \
  'https://docs.cybersign.gt/_mock/openapi/documents/download-url?document-path=user-uuid%2Fonboarding-ulid%2Fdocument-name.pdf' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Pre-signed download URL generated successfully.

Bodyapplication/json
download_urlstring(url)required

The pre-signed URL that can be used to download the specified document.

Example: "https://your-bucket-name.s3.your-region.amazonaws.com/user-uuid/onboarding-ulid/documento.pdf?AWSAccessKeyId=...&Expires=...&Signature=..."
Response
application/json
{
  "download_url": "https://your-bucket-name.s3.your-region.amazonaws.com/user-uuid/onboarding-ulid/documento.pdf?AWSAccessKeyId=...&Expires=...&Signature=..."
}

Sign Uploaded Document

Request

Applies a digital signature to a previously uploaded document using the specified user certificate and OTP verification. Supports visible and invisible signatures.

Security
user_bearer_auth
Path
doc-ulidstring(ulid)required

The unique ULID of the document (obtained from the upload URL response) to be signed.

Example: 01JE9KCR0H22PDY9C1GYZABCDE
Bodyapplication/jsonrequired
file_namestringrequired

The identifier of the user's certificate (obtained from GET /certificates) to use for signing.

Example: "my-file.pdf"
certificate_idstringrequired

The identifier of the user's certificate (obtained from GET /certificates) to use for signing.

Example: "cert_thmb_abc123def456"
signature_formatstringrequired

The cryptographic standard to use for the signature.

Default "PKCS7"
Value"PKCS7"
Example: "PKCS7"
otpobject(OtpInput)required

One-Time Password details for MFA verification.

otp.​valuestringrequired

The actual OTP code provided by the user.

Example: "123456"
otp.​typestringrequired

The method used to deliver/generate the OTP.

Enum"sms""totp""email""biometric"
Example: "sms"
visible_signature_optionsobject(VisibleSignatureOptions)

Optional parameters to configure a visible signature appearance block in the PDF. Omit this object for an invisible signature.

curl -i -X POST \
  https://docs.cybersign.gt/_mock/openapi/documents/01JE9KCR0H22PDY9C1GYZABCDE/sign \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "file_name": "my-file.pdf",
    "certificate_id": "cert_thmb_abc123def456",
    "signature_format": "PKCS7",
    "otp": {
      "value": "123456",
      "type": "sms"
    },
    "visible_signature_options": {
      "page_number": 0,
      "position_x": 0.4378,
      "position_y": 0.3577,
      "include_date": true,
      "include_initials": false,
      "include_motive": true,
      "include_signature_graphic": true,
      "motive": "Aprobación de documento"
    }
  }'

Responses

Document signed successfully.

Bodyapplication/json
messagestringrequired

Confirmation message.

Example: "Document signed successfully."
doc_ulidstring(ulid)required

The ULID of the document that was signed.

Example: "01JE9KCR0H22PDY9C1GYZABCDE"
Response
application/json
{
  "message": "Document signed successfully.",
  "doc_ulid": "01JE9KCR0H22PDY9C1GYZABCDE"
}

Certificates

Operations related to managing digital certificates.

Operations