ZealiD CSC API in detail

Preliminaries

Integration checklist

  1. API credentials are required:
    • client_id
    • client_secret
  2. Base ZealiD (“Hermes”) backend URL is required:
    • Testing environment: https://hermes-dev.zealid.com
    • Production environment: https://core-hermes.zealid.com
    • URL prefix to be added before CSC endpoints
      • Current version: /mediator/api/csc/v1.0
      • Example of full testing URL (1st CSC endpoint): https://hermes-dev.zealid.com/mediator/api/csc/v1.0/oauth2/authorize

📘

Get API credentials

Contact [email protected] for API credentials

🚧

Use correct subdomain:

  • core-hermes - production environment
  • hermes-dev - testing environment

ZealiD apps for integration

Environment

Android

iOS

Production (live)

In Google App Store

In Apple App Store

Testing (integration)

Contact: [email protected]

Contact: [email protected]

🚧

Please note

It is usually strongly advised to only have one ZealiD app per mobile device. Therefore when installing a new build (different environment), it is recommended to uninstall the previous build first; and to not install multiple ZealiD apps from different environments on the same device.

Inventory of related specs

Most important related documentation for reference (not strictly needed for integration):

  1. CSC API v1 spec: https://cloudsignatureconsortium.org/wp-content/uploads/2020/01/CSC_API_V1_1.0.4.0.pdf

  2. RFC 6749, The OAuth 2.0 Authorization Framework: https://tools.ietf.org/html/rfc6749

  3. RFC 7521, Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants: https://tools.ietf.org/html/rfc7521

General API sequence diagram

CSC endpoints

Endpoint, parameter, sample request and response listing is provided below. Please first read additional important notes:

Billing

  • If additional information is not provided, the client integrating and calling the API is the one to be billed

  • However, the client may sometimes need to act as a partner facilitating other client companies (which are to be the billable entity)

  • CSC-spec-compatible parameter is to be used for this purpose, in this instance: clientData. You do not pass it in the initial oauth2/authorize call (because no client authentication takes place at that point - i.e. data is not reliable, trust-wise), but it can be passed as an optional parameter to the subsequent POST oauth2/token call

  • If this parameter is not passed, it is assumed that the calling party is the actual billable entity

  • If this additional parameter is passed, it is understood that this ID is to be billed; ZealiD saves this ID as well

CSC endpoint API notes

  • oauth2 (not oauth) general structure is used, to conform to CSC v1. Here is the reference CSC v1 spec which we're using as our basis: https://cloudsignatureconsortium.org/wp-content/uploads/2020/01/CSC_API_V1_1.0.4.0.pdf

  • Note the endpoint number (currently there are 5 different endpoints): these should normally be called in the order as given, i.e. 1 -> 2 -> 3 -> 4 -> 5.

  • Input parameter names (variables) always match CSC spec

  • Where possible, descriptions are adapted from the CSC spec and modified as necessary

  • Input parameter list is in some cases ZealiD-specific, so please use this documentation as the definitive ZealiD CSC reference

  • CSC mixes underscore_based and camelCase parameter names (which can sometimes be confusing), so please beware when integrating

  • CSC spec references are included; whenever there is a possible divergence, notes are included

  • We will be sending a unique ID (access_token) instead of full SAD that is uniquely linked with SAD, and you will be including the ID in the signHash request

  • You need to call signHash after redirect in a limited amount of time as otherwise signing transaction (and the SAD) will expire

  • Note from CSC spec: "NOTE 4: Although RFC 3986 doesn’t define length limits on URIs, there are practical limits imposed by browsers and web servers. It is RECOMMENDED not to exceed an URI length of 2083 characters for maximum interoperability." (p. 20)

Other additional notes

  • We use Natural Persons Semantics Identifier (ETSI 319 412-1)

  • Our Common Name is compiled from Name, Surname and Serial Number; currently and by default, Serial Number follows ETSI 319 412-1 5.1.3

ZealiD CSC API endpoints

Info

API reference for developers
Returns information about the remote service and the list of the API methods it
supports

Example request:

curl https://hermes-dev.zealid.com/mediator/api/csc/v1.0/info
    -X GET
    -d @- << EOF
EOF

Example response

{
  "authType": [
    "oauth2code"
  ], 
  "description": "ZealiD Qualified eSignature", 
  "lang": "en-US", 
  "logo": "https://www.zealid.com/hubfs/zealid/group-3.svg", 
  "methods": [
    "oauth2/authorize", 
    "oauth2/token", 
    "signatures/signHash", 
    "credentials/info", 
    "oauth2/revoke"
  ], 
  "name": "ZealID Trust Services", 
  "oauth2": "https://hermes-dev.zealid.com/mediator/api/csc/v1.0/oauth2", 
  "region": "LT", 
  "specs": "1.0.4.0"
}

Authorize

API reference for developers
Initiate an OAuth 2.0 authorization flow.
CSC spec reference 8.3.2 in CSC v1

📘

Required input

HEADERS
Content-Type (string) should be "application/x-www-form-urlencoded"

QUERY PARAMS

  • scope (string) must be set to "credential"
  • response_type (string) the value shall be “code”.
  • client_id (string) the unique client ID previously assigned to the client by the remote service (ZealiD).
  • redirect_uri (string/optional) the URL where the user will be redirected after the authorization process has completed. Only a valid URI preregistered with the remote service (i.e. which starts with the base URL preregistered with ZealiD) SHALL be passed. If omitted, the remote service will use the default redirect URI pre-registered by the client.
  • numSignatures (int) the number of signatures to authorize. Must be an integer matching the number of hashes.
  • hash (string) one or more base64url-encoded hash values to be signed. Multiple hash values can be passed as comma separated values, e.g. oauth2/authorize?hash=dnN3ZX…ZmRm,ZjIxM3…Z2Zk,… (The parameter name is singular “hash” to match CSC spec).

Example request

curl https://hermes-dev.zealid.com/mediator/api/csc/v1.0/oauth2/authorize?
response_type=code&
client_id=$OAuth2_client_id&
redirect_uri=$OAuth2_redirect_uri&
scope=credential&
numSignatures=1&
hash=MTIzNDU2Nzg5MHF3ZXJ0enVpb3Bhc2RmZ2hqa2zDtnl4
    -X GET
    -H "Content-type: application/x-www-form-urlencoded"

Example response

HTTP/1.1 302 Found
Location: <OAuth2_redirect_uri>?code=HS9naJKWwp901hBcK348IUHiuH8374&
state=12345678

Token

API reference for developers
Obtain an OAuth 2.0 access token
CSC spec reference 8.3.3 in CSC v1

Note: we diverge from CSC spec by giving credential_id on successful response - this is so that client does not have to call credentials/info before signatures/signHash

📘

Required input

HEADERS
Content-Type (string) should be "application/x-www-form-urlencoded"

QUERY PARAMS

  • grant_type (string) the grant type, which depends on the type of OAuth 2.0 flow. Must be set to “authorization_code”
  • code (string) the authorization code returned by oauth2/authorize query parameter during redirect. It SHALL be bound to the client identifier and the redirection URI.
  • client_id (string) the unique client ID previously assigned to the client by the remote service (ZealiD).
  • client_secret (string) this is the client secret previously assigned to the client by the remote service (ZealiD).
  • client_data (string/optional) this CSC parameter is to be re-used and supplied to ZealiD when it is necessary to indicate the client ID to be billed. By default, the client_id is the ID to be billed. However, when the client integrating the API is a partner and a connecting business client is to be billed instead, clientData here must be set to the client ID to be billed.

📘

Expected output

  • access_token (string) the short-lived OAuth 2.0 access token
  • token_type (string) type of the token
  • expires_in (int) the lifetime in seconds of the token
  • credential_id (string) the unique identifier associated to the credential.

Example request:

curl url https://hermes-dev.zealid.com/mediator/api/csc/v1.0/oauth2/token?grant_type=authorization_code&code=$authorization_code&client_id=$client_id&client_secret=$client_secret
 -X POST
 -H "Content-type: application/x-www-form-urlencoded"

Example response:

{
"access_token": "3XlFQZ3ndFhkXf9P24/CKN69L8gdSYp5H3XlFQZ3ndFhkXf9P2",
"token_type": "SAD",
"expires_in": 300,
"credential_id": "cust_GX0112348"
}

Sign Hash

API reference for developers
Calculate a raw digital signature from one or more hash values.
CSC spec reference 11.9 in CSC v1

📘

Required input

HEADERS
Content-Type (string) should be "application/json"

BODY PARAMS

  • credentialID (string) the credential_id returned in oauth2/token
  • SAD (string) the access_token returned in oauth2/token
  • hash (array of strings) one or more hash values to be signed. This parameter SHALL contain the Base64-encoded raw message digest(s). The hash list must match the initial set of hashes passed via oauth2/authorize

📘

Expected output

  • signatures (array of strings) one or more Base64-encoded signed hash(s). In case of
    multiple signatures, the signed hashes will be returned in the same order as the corresponding hashes provided as an input parameter.

Example request:

curl https://hermes-dev.zealid.com/mediator/api/csc/v1.0/signatures/signHash
    -X POST
    -H "Content-type: application/json"
    -d @- << EOF
{
    "credentialID": "cust_GX0112348",
    "SAD": "hermes_token_asdf",
    "hash": [
    "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=",
    "c1RPZ3dPbSs0NzRnRmowcTB4MWlTTnNwS3FiY3NlNEllaXFsRGcvSFd1ST0="
    ]
}
EOF

Example response:

{
    "signatures": [
        "KedJuTob5gtvYx9qM3k3gm7kbLBwVbEQRl26S2tmXjqNND7MRGtoew==",
        "Idhef7xzgtvYx9qM3k3gm7kbLBwVbE98239S2tm8hUh85KKsfdowel=="
    ]
}

Credentials Info

API reference for developers
Returns information on a signing credential, its associated certificate and a description of the supported authorization mechanism.
CSC spec reference 11.5 in CSC v1

📘

Required input

HEADERS
Authorization (string) "Bearer $access_token" where access_token - the token returned in oauth2/token
Content-Type (string) should be "application/json"

BODY PARAMS

  • credentialID (string) the credential_id returned in oauth2/token (the unique identifier associated to the credential.)

📘

Expected output

  • key (dictionary):
    • status (string) the status of the signing key of the credential:
      • “enabled”: the signing key is enabled and can be
      used for signing.
      • “disabled”: the signing key is disabled and cannot be
      used for signing. This MAY occur when the owner
      has disabled it or when the RSSP has detected that
      the associated certificate is expired or revoked.
    • algo (array of strings) the list of OIDs of the supported key algorithms. For
      example: 1.2.840.113549.1.1.1 = RSA encryption, 1.2.840.10045.4.3.2 = ECDSA with SHA256.
    • len (int) the length of the cryptographic key in bits.
  • cert (dictionary):
    • status (string) the status of validity of the end entity certificate.
    • certificates (array of strings) one or more Base64-encoded X.509v3 certificates from
      the certificate chain. If the certificates parameter is “chain”, the entire certificate chain is returned
      with the end entity certificate at the beginning of the array. If the certificates parameter is “single”, only the end entity certificate is be returned. If the certificates parameter is “None”, this value is not returned.
    • issuerDN (string) the Issuer Distinguished Name from the X.509v3 end entity certificate as UTF-8-encoded character string according to RFC 4514. This value is returned when certInfo is “true”.
    • serialNumber (string) the Serial Number from the X.509v3 end entity certificate represented as hex-encoded string format. This value is returned when certInfo is “true”.
    • subjectDN (string) the Subject Distinguished Name from the X.509v3 end entity certificate as UTF-8-encoded character string, according to RFC 4514. This value is returned when certInfo is “true”
    • validFrom (string) the validity start date from the X.509v3 end entity certificate as character string, encoded as GeneralizedTime (RFC 5280) (e.g. “YYYYMMDDHHMMSSZ”). This value is returned when certInfo is “true”.
    • validTo (string) the validity end date from the X.509v3 end entity certificate as character string, encoded as GeneralizedTime (RFC 5280) (e.g. “YYYYMMDDHHMMSSZ”). This value is returned when certInfo is “true”
  • authMode (string) specifies one of the authorization modes. For more information also see section 8.2 in CSC v1 [1]:
    • “implicit”: the authorization process is managed by the remote service autonomously. Authentication factors are managed by the RSSP by interacting directly with the user, and not by the signature application.
    • “explicit”: the authorization process is managed by the signature application, which collects
    authentication factors like PIN or One-Time Passwords (OTP).
    • “oauth2code”: the authorization process is managed by the remote service using an OAuth 2.0 mechanism based on authoritzation code as described in Section 1.3.1 of RFC 6749 [2].
  • multisign (int) a number equal or higher to 1 representing the maximum number of signatures that can be created with this credential with a single authorization request (e.g. by calling credentials/signHash method, as defined in section 11.9 in CSC v1 [1], once with multiple hash values or calling it multiple times). The value of numSignatures specified in the authorization request SHALL NOT exceed the value of this value.
  • lang (string) the lang as defined in the Output parameter table in section 11.1 in CSC v1 [1]

Example request:

curl https://hermes-dev.zealid.com/mediator/api/csc/v1.0/credentials/info
    -X POST
    -H "Authorization: Bearer $access_token"
    -H "Content-type: application/json"
    -d @- << EOF
{
    "credentialID": "cust_GX0112348",
}
EOF

Example response:

{
"key":
{
"status": "enabled",
"algo": [ "1.2.840.113549.1.1.1", "0.4.0.127.0.7.1.1.4.1.3" ],
"len": 2048
},
"cert":
{
"status": "valid",
"certificates":
[
"<Base64-encoded_X.509_end_entity_certificate>",
"<Base64-encoded_X.509_intermediate_CA_certificate>",
"<Base64-encoded_X.509_root_CA_certificate>"
],
"issuerDN": "<X.500_issuer_DN_printable_string>",
"serialNumber": "5AAC41CD8FA22B953640",
"subjectDN": "<X.500_subject_DN_printable_string>",
"validFrom": "20180101100000Z",
"validTo": "20190101095959Z"
},
"authMode": "explicit",
"multisign": 5,
"lang": "en-US"
}

Revoke

API reference for developers
Revoke an OAuth 2.0 access token
CSC spec reference 8.3.5 in CSC v1

📘

Required input

HEADERS
Authorization (string) "Bearer $access_token" where access_token - the token returned in oauth2/token
Content-Type (string) should be "application/json"

BODY PARAMS

  • token (string) the access_token returned in oauth2/token

Example request:

curl https://hermes-dev.zealid.com/mediator/api/csc/v1.0/oauth2/revoke
    -X POST
    -H "Authorization: Bearer $access_token"
    -H "Content-type: application/json"
    -d @- << EOF
{
    "token": "$access_token",
}
EOF

Example response:

HTTP/1.1 204 No Content