IvSign services technical documentation / API V4

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.

As of IvSign version 8 (API 4) 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: simple hash signatures, document signatures, time stamp signatures and verifications. As well as the monthly quantity allowed to be performed. To know the restrictions of a license code, contact with the project manager.

As of IvSign version 8 (API 4) 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: simple hash signatures, 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.

As of IvSign version 8 (API 4) the 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 the organization.
The super administrator user is able to perform more operations than an administrator user. A part from 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/v4/CATEGORY/ACTION

For instance, to do a Login action in Auth category:
https://demo.ivsign.net/Keyman/rest/v4/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/KeymanServiceV4.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 Auth/Login method using the following parameters.

Request and response example:

In this example the token is: KV2BxG3kj5YvgQ3N1AOP7Oj7BNSUQot/T087Z+RdZReo=

Obtaining a valid token using a valid token is done through 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: KMmu6rUyQTUq8fFAxOKM1WR2uDekpGnND3BvAJvScInDF4TfF6rh4CqnayZfHdEiZ

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 user's login without generating a token is done through Auth/LoginCheck 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/LoginCheck_Validation method.

Request and response example:

Checking tokens is done through the Auth/TokenCheck 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:

Creating users is done through the User/Add method.
Administrator privileges or higher are needed.

Request and response example:

Obtaining user data is done through the User/Get method.
The method returns a specific user data.

Request and response example:

Setting user data is done through the User/Set method.
This method allows to change user personal data and its password.
The no null values established will be used to modify data of the user indicated on the user.userid field.

Request and response example:

Deleting user is done through the User/Del method.
Only users without certificates can be deleted. A user can not delete itself. Administrator privileges or higher are needed to delete users

Request and response example:

Listing users is done through the User/List method.
The method list users depending on some filter parameters. Administrator privileges are needed.

Request and response example:

Searching user's information is done through the User/Find method.
The difference between User/Get and User/Find is that User/Find search on any available authentication provider and create the user in the database if it doesn't exist.

Request and response example:

Obtaining user privileges level is done through the User/Level method.

Request and response example:

Moving a user to another organization is done through the User/OrgaMove method.
Both organizations must belong to the agent user organization chain.

Request and response example:

Creating new users without token session is done through the User/PublicAdd method.
All these users aren't valid, they will need to be validated once they will access to IvSign.

Request and response example:

Renaming users, changing its userid, is done through the User/Ren method.
The renamed user will loose its previous auditory records.

Request and response example:

Checking which user field are allowed to be modified is done through the User/Modifiablefields method.

Request and response example:

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

Request and response example:

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

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:

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:

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:

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:

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:

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.

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:

Obtaining certificate provider, CA, certificate public key is done through the Cert/RefCERGet method.

Request and response example:

Listing certificate provider certificates, CA, is done through the Cert/RefList 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:

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

Request and response example:

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

Request and response example:

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:

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

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:

Creating new public certificates on IvSing using its public key is done through the PubCert/Add method.

Request and response example:

Método para obtener un certificado público de IvSign.

Request and response example:

Setting public certificates is done through the PubCert/Set method.

Request and response example:

Deleting public certificates is done through the PubCert/Del method.