IvSign services technical documentation / API V5

Authentication on IvSign requires three parameters: user, password and organization. A part from that, as of IvSign version 8 (API 4), the parameters integration module and device are needed. More information about modules will be provided in further sections.
To be able to perform device authentication, the device must be authorized for the user who wants to authenticate. Depending on the user's organization or the authentication module it is possible that the device authorization won't be requested.

During user's authentication process, indicating module and its module key will be needed.
Each module has a list of methods and/or groups of methods that allow or deny the access to them. To know which methods are allowed to access or denied to access to depending on a module, please contact with the project manager.

Organizations must have a license code. Associated to the license code, there signature privileges and monthly quantity restrictions. As well as limits on the quantity of users and certificates an organization can hold.
Those limits are maximum users and certificates an organization can hold. A part from that, this parameters allows or denies perform several actions: document signatures, time stamp signatures and verifications. As well as the monthly quantity allowed to be performed. To know which restrictions an organization license code has, contact with the project manager.

All INHOUSE environments where IvSign is installed must have a product license. This license code has associated a maximum number of users, certificates and organizations a environment can hold.
A part from that there are restrictions to perform several actions: document signatures, time stamp signatures and verifications. As well as the monthly quantity allowed to be performed. There are also some restrictions referring to IvSign components a environment can hold, such as keyman, certmanager, pscintegration or ivssm.

There are four level user privileges: basic user, administrator user, super administrator user and system administrator user. Each one of these profiles is allowed to access some methods. On each detail method explanation there is an indication of which level privileges are required to access to it and the requested conditions to do it.

The administrator user is able to perform operations on itself and on its organization other users. As well as manage some aspect of its organization.
The super administrator user is able to perform more operations than an administrator user. It is able to manage aspects not only of its organizations but also its child organization and all organizations that come from them. As well as manage their users.
The system administrator user is able to perform any action on any organization or users without restrictions.

REST service uses JSON notation for in and out of the service.
It is required a POST request to each operation URL with the request data.
The Auth category operations will return a session token. It will be needed on each operation and must be sent on the Authentication headline.

In order to access to each REST method it is needed to create the URL using the following example:
https://ENVIRONMENT/Keyman/rest/v5/CATEGORY/ACTION

For instance, to do a Login action in Auth category:
https://demo.ivsign.net/Keyman/rest/v5/auth/login

SOAP service uses WCF Microsoft services, allowing a quick implementation through .NET resources.
The Auth category operations will return a session token. It will be needed on each operation and must be sent as a parameter.

The URL service will depend on the environment it is wanted to access, using the following format:
https://ENVIRONMENT/Keyman/KeymanServiceV5.svc

Once the service is referenced, the operations described below in this document will be available. The name of each method will be the union between the category and the action.
For instance, to do a Login action in Auth category the .NET method would be:
AuthLoginResponse AuthLogin(AuthLoginRequest request);

Obtaining a session token is done trough the Auth/Login method using the following parameters.

Request and response example:

In this example the token is: KrFWFozz0Mt5z+6A7vnz8VjWD9Xbt2/vROvRfJqtXjXuWBIVztI26HNL1Ko0ZAWqM8rzzXGdXN6QYWVqfcYADYA3OwIqZERoBvJdEYSuHimA=

Obtaining a valid token using a valid token is done through the Auth/LoginToken method.
This method allows to re-use valid user credentials through a valid token for generating a new one using another module and device.

Request and response example:

In this example the token is: Kb3UgDXnKbpxpURvzdT8qaw2FVtd442RHcPCMdQjxy6fzemOSyQjmdeDMScenfew3UslQ9mBE+oR3Po4KFE5EvEgDPoIajcQpykd7a99D3Ug=

Checking user's login without generating a token is done through the Auth/Check method.
The method allows only Windows authentication or user/password authentication.

Request and response example:

Checking that the user validation code sent by email is correct is done through the Auth/CheckValidation method.

Request and response example:

Impersonating other users is done through the Auth/Impersonate method.
This method is used to perform actions in the name of the impersonated used. It is not possible to impersonate users with higher privileges.

Request and response example:

Recovering passwords is done through the Auth/PasswordRecovery method.

Request and response example:

Checking that the users of an organization, or authentication provider, are able to change their passwords is done through the Auth/ProviderModifiablePass method.

Request and response example:

Checking tokens is done through the Auth/TokenCheck method.

Request and response example:

Listing auditory records is done through the Audit/List method.
The method returns the auditory records based on the request parameters and the pagination.

Request and response example:

Obtaining auditory categories and action data is done through the Audit/Info method.
The returned data depends on the recorded performed operations.

Request and response example:

Listing agent user organization authentication providers is done trough the AuthProvider/List method.

Request and response example:

Importing certificates PFX or P12 with private key is done through the Cert/ImportPFX method.
The method imports the certificate to the agent user or to the specified user.

Request and response example:

Deleting certificates is done through the Cert/Del method.
Once the certificate is erased, it is not possible to be recovered.

Request and response example:

Obtaining a certificate data is done through the Cert/Get method.

Request and response example:

Listing certificates is done through the Cert/List method.
The list can contain from a user's certificates up to all system's certificates, depending on agent user privileges.

Request and response example:

Modifying certificate data is done through the Cert/Set method.

Request and response example:

Getting certificate public key is done through the Cert/CERGet method.

Request and response example:

Getting certificate certification complete chain, as of its immediate superior CA until root certificate (if it is possible) is done through the Cert/ChainGet method.

Request and response example:

Listing currently available certificates is done through the Cert/ListAvailable method.
The method list only the certificates allowed to be used on the current application. Only agent user certificates will be listed. Those invalid certificates due to usage rules or policy rules won't be listed. Expired and/or revoked certificates may be omitted during the listing by having the hiderevoked and/or hideexpired configurations enabled.

Request and response example:

Moving certificates from one user to another is done through the Cert/Move method.

Request and response example:

Checking certificates pin is done through the Cert/PinCheck method.

Request and response example:

Setting a new pin to a certificate is done through the Cert/PinSet method.

Request and response example:

Obtaining certificate's provider, CA, certificate public key is done through the Cert/RefGetCER method.

Request and response example:

Linking reference certificates, CA certificates, to a user is done through the Cert/RefLink method.

Request and response example:

Listing certificate provider certificates, CA, is done through the Cert/RefList method.

Request and response example:

Creating and installing certificates is done through 3 methods. The first one is the Cert/RSAGen.
The combining of the 3 methods allows to centralize a extern CA certificate into IvSign.
This method generates certificate public and private key.

Request and response example:

Creating and installing certificates is done through 3 methods. The second one is the Cert/GenCSR.
The combining of the 3 methods allows to centralize a extern CA certificate into IvSign.
This method sets subject parameter to the certificate.

Request and response example:

Creating and installing certificates is done through 3 methods. The third one is the Cert/InstallCER.
The combining of the 3 methods allows to centralize a extern CA certificate into IvSign.
This method installs the public certificate key into IvSign. This public key must be signed by the proper CA before using this method.

Request and response example:

Certificate replacement is done through the Cert/Replace method.
This method can be used, for instance, when a certificate is about to expire. It can be replaced for its substitute and all the delegations and referred properties will be assigned to the new one.

Request and response example:

Searching certificates by its public key is done through the Cert/Search method.

Request and response example:

Listing certificate providers is done through the CertProvider/List method.

Deleting certificates from the certificate's bin is done through the CertTrash/Del method.
Once the certificate is erased, it is not possible to be recovered.

Request and response example:

Getting bin certificates data is done through the CertTrash/Get method.

Request and response example:

Listing certificate bin certificates is done through the CertTrash/List.
The list can contain from a user's certificates up to all system's certificates, depending on agent user privileges.

Request and response example:

Sending certificates to the certificate bin is done through the CertTrash/Move method.
The Cert object becomes a CertTrash object.

Request and response example:

Restoring certificates from the certificates bin is done through the CertTrash/Rest method.
The CertTrash object becomes a Cert object.

Request and response example:

Creating a new configuration is done through the Config/Add method.

Request and response example:

Deleting a configuration is done through the Config/Del method.

Request and response example:

Getting a configuration is done through the Config/Get method.

Request and response example:

Listing configurations is done through the Config/List method.
Only the allowed configurations to the agent user will be listed, according to the agent user privileges level.

Request and response example:

Setting a configuration's value is done through the Config/Set method.

Request and response example:

Getting public configuration is done through the Config/PublicGet method.
The difference between configuration and public configuration is that public configuration has no user level privileges restrictions.

Request and response example:

Listing public configuration is done through the Config/PublicList method.
The difference between configuration and public configuration is that public configuration has no user level privileges restrictions.

Request and response example:

IvSign certificate delegations are done through the Deleg/Add method.
Once the delegation is created, users can be assigned to it. For each user assigned a copy certificate of the delegation certificate will be created.

Request and response example:

Deleting a delegation is done through the Deleg/Del method.
The delegation must have no users associated to it.

Request and response example:

Getting delegation data is done through the Deleg/Get method.