Introduction

Welcome to the CSC API from SIGN8! This guide is designed to help you integrate our CSC API seamlessly into your system. The CSC API can be used to create digital signatures on documents and data. It follows the standards set by the Cloud Signature Consortium (CSC).

The CSC is a group of organisations that work together to define standards for electronic signatures in the cloud. By adhering to these standards, our electronic signature solution is interoperable with other CSC-compliant systems. This means that documents signed with our API can be recognised and accepted by other electronic signature platforms that also follow the CSC guidelines.

First steps

To access our CSC API, you need to purchase an Enterprise or Volume-based subscription. Complete the following steps after purchase:

Step 1: Access the documentation: navigate to the Administration section in your SIGN8 app. There you will find the API button that gives you access to the technical documentation for your developers.

Step 2: Request integration access: Contact our team and let them know that you would like to integrate our solution into your system. Our developers will provide you with the necessary access.

Step 3: Access to systems: When you access the documentation, you will be given access to the production system and the test system, each with a corresponding licence. This allows you to develop and test your integration in a controlled environment.

Terms and definitions

• Signature app: This is the software or service that uses the SIGN8 API to create digital signatures.
  
• HTTPS: This is a secure method of sending data over the internet.
  
• UUID: This is a unique ID used in computer systems.
  
• Access Token: This is a special code that allows a computer system to access protected resources. It is a character string that represents an authorisation granted to the client. The character string is not normally visible to the client.
  
• Authentication Factor: These are details that are used to verify the identity of a user.
  
• Credential: A digital object used to create digital signatures on the Internet.
  
• Digital signature: A digital code generated by encryption with a public key that is attached to an electronically transmitted document to verify its content and the identity of the sender.
  
• Signature activation data: This is data used to control a digital signature process.
  
• OAuth 2.0: Stands for ‘Open Authorisation’ and is a standard protocol for authorisation. It allows a website or application to access resources hosted by other web applications on behalf of a user without revealing the user's long-term credentials or even identity.
  

Here are some important concepts related to OAuth 2.0:

1. Resource Owner: The user or system that owns the protected resource and can grant access to it.
   
2. Client: The system that requires access to the protected resources. To be able to access the resources, the client must be in possession of the corresponding access token.
   
3. Authorisation server: This server receives requests for access tokens from the client and issues them after successful authentication and approval by the resource owner.
   
4. Resource Server: A server that protects the user's resources and accepts the client's access requests.
   
5. Access Tokens: These are data that represent the authorisation to access resources on behalf of the end user.
   
6. Scopes: These are used to define the exact reason for which access to resources may be granted.
   

OAuth 2.0 is primarily intended as a means of granting access to a range of resources such as remote APIs. It introduces a layer of authorisation and separates the role of the client from that of the resource owner.

Abbreviations

• API : application programming interface
  
• CSC : Cloud Signature Consortium
  
• HSM: hardware security module
  
• RSCD: remote signature creation device
  
• RSSP: remote signing service provider
  
• SAD: signature activation data SAM: signature activation module
  
• SCAL1: sole control assurance level 1
  
• SCAL2: sole control assurance level 2

The architecture

For more information, please refer to the Cloud Signature Consortium standard.

The remote signing process consists of four main steps:

Step 1: Obtaining the document: the signature application receives the document to be signed from the user. If necessary, it also receives certificates, revocation information and timestamps from a trust service provider

Step 3: Binding Credentials: The RSSP works with a Certificate Authority (CA) to bind the credentials. Sometimes the CA also helps to generate the signature key

Step 4: Authorisation: Authorisation of the service or access to the credentials can be done in two ways. It can either be done via the signature application or via a redirection to an external OAuth 2.0 authorisation server. In many cases, this authorisation server is part of the RSSP

This process ensures that the document is securely signed and that the user's credentials are properly authorised.

Flows

There are two different ways to use the SIGN8 CSC API. The first requires the signing application to redirect the user twice. The second method requires only one redirect. Both methods involve different steps, such as requesting authorisation codes, exchanging codes for access tokens, requesting signatures and revoking access tokens.

Flow 1

The first flow uses authorisation by service and credential. Therefore, the signing application must redirect the user twice.

The diagram shows the process involving a user, a signature application, an authorisation server and a remote service.

A simplified explanation follows:

User: This is the person who initiates the process. He interacts with the signature application to sign a document

Signature Application: This is the software or service with which the user interacts. It communicates with the authorisation server and the remote service to enable the document to be signed

Authorisation Server: This is the system with which the Signature Application communicates. It is responsible for authorising the user and the signature application to perform the signature process

Remote Service: This component is responsible for carrying out the signature process using the credentials provided by the user. It receives requests from the signature application to initiate the signature process, processes these requests and interacts with the credentials provided by the user to generate the electronic signature.

What happens step by step

​

Step 1: Initiation by the user:

The electronic signature process begins when a user decides to sign a document using the signature application provided by Company X. This can be initiated by the user. This can be initiated by the user who needs to sign a contract, agreement or other document that requires their electronic signature.

Step 2: Request authorisation code (initial):

The signature application, upon receiving the user's request to sign a document, communicates with the authorisation server to obtain an authorisation code. This code serves as a temporary token that enables the signature application to authenticate the user's identity.

Step 3: User login:

To authenticate the user, the signature application prompts them to log in to their account or give their consent to access their signature. This process usually involves a pop-up or redirected page where the user enters their credentials or gives their authorisation.

Step 4: Return of the authorisation code (initial):

After successful authentication or consent, the authorisation server generates an authorisation code and sends it back to the signature application. This code serves as proof that the user has been authenticated and authorised to access their signature.

Step 5: Exchange the code for an access token (initial):

With the authorisation code received, the signature application sends a request to the authorisation server to exchange it for an Access Token. This access token serves as a long-term proof of authorisation that allows the signature application to access the user's signature without the user having to log in repeatedly.

Step 6: Returning the access token (initial):

After a successful exchange, the authorisation server returns the access token to the signature application. This token is stored securely and used for subsequent requests to access the user's signature data.

Step 7: Request credential information:

To facilitate the signature process, the signature application requires information about the user's available credentials. It sends a request to a remote server to obtain this information, including details about the types of credentials the user can use to sign.

Step 8: Return the credential information:

The remote server responds to the signature application's request by providing information about the credentials available to the user. This information allows the signature application to determine which credentials to use for the signing process.

Step 9: Request authorisation code (Scope=Credential):

In some cases, the signature application requires special authorisation to access certain credentials for the signing process. It requests a further authorisation code from the authorisation server, specifying the scope as ‘Credential’.

Step 10: Authorise credentials with OTP:

If additional authorisation is required for certain credentials, such as through a one-time password (OTP), the user follows the prompts on a pop-up page or redirected page to authorise the credentials with the authorisation server.

Step 11: Exchange the code for the access token (credential scope):

After the signature application receives the required authorisation, it exchanges the authorisation code received for specific credentials for another access token. This token is specific to the authorised credential(s) and grants access to them.

Step 12: Return of the access token (credential scope):

The authorisation server returns the access token for the authorised credential(s) to the signature application. This token is used exclusively for accessing the specified credential(s) during the signing process.

Step 13: Requesting the signature:

With the received Access Token and credential information, the signature application sends a request to the remote server to start the signing process. This request contains the document to be signed and all necessary metadata.

Step 14: Return signature:

The remote server processes the signature request from the signature application, supports the signing process using the provided credentials and sends the signed document or confirmation of the signature back to the signature application.

Step 15: Revoke token access (optional):

Once the signing process is complete, the signature application can revoke the access token(s) granted to it by sending a request to the authorisation server. This step ensures that the application can no longer access the user's credentials without explicit consent, which increases security and data protection.