API Overview and API Reference: Difference between pages

From SafeStamper API documentation
(Difference between pages)
Jump to navigation Jump to search
m (1 revision imported)
 
m (1 revision imported)
 
Line 1: Line 1:
= API architecture =
= Authorization API Reference =
To create and manage user authorizations.


Safe Stamper API is a REST-like interface to Safe Stamper services.
You don't need to use these operations if your API keys are already linked to your user account.


There are two trust levels for applications using Safe Stamper API.
== API operations ==
* [[createauth]]: Create a pending authorization key that must be authorized by a user.
* [[authstate]]: Check the status of an authkey
* [[deleteauth]]: Delete a user authorization


* '''Standard API''': This comprises the bulk of Safe Stamper services. You need to generate a user authorization key for each Safe Stamper user that works through your application.
* '''Partners API''': Some components are reserved for use by Safe Stamper partners. Contact [mailto:community@safecreative.org community@safecreative.org] if you want to become a partner.


= Obtaining the keys to use the API =


To use the Safe Stamper API, you need a pair of keys:
= Certificates API Reference =
* A '''shared key''' that identifies your client application
* A '''private key''' used for signing your requests


To get your pair of API keys, you can contact us through [https://www.safestamper.com/contact Safe Stamper contact form]
To list and manage user certificates


= Arena sandbox environment =
== API operations ==


There is a testing environment available at http://arena.safestamper.com.
* [[certificates]]: List certificates of the user
* [[certificate/get]]: Download a certificate. This operation works on behalf of the certificate owner, so it downloads the certificate even if it is private or password-protected.
* [[certificate/accesslevel]]: Set the access protection for a certificate
* [[certificate/delete]]: Delete certificate
* [[certificate/tag]]: Set tag to certificate
* [[certificate/notes]]: Set notes to certificate


This is a complete replica of the Safe Stamper web site, including an API server. You can create user accounts, make certifications and request API keys.
= Static Web Page API Reference =


It is strongly encouraged to use the arena environment for testing the API before using your application on the real service. To do so, you must request your application key at [https://www.safestamper.com/contact Safe Stamper contact form]. When we activate your api keys, you can start testing the API.
To create static web pages certificates


As a matter of fact, API keys for production environment will not be activated if the application has not been previously tested against the arena environment
== API operations ==
* [[web/stamp]]: Send URLs for static page certification
* [[web/status]]: Check the status of a certification job


= Accessing the API =
== Callbacks ==
When calling [[web/stamp]] you can provide a callback URL:


Safe Stamper API Services are accessible via a REST-like interface. The interface is rooted at <code><nowiki>http://www.safestamper.com/api/</nowiki></code> for production services and <code><nowiki>http://arena.safestamper.com/api/</nowiki></code> for the arena environment.
* [[Web API callbacks]]


All requests must be done using the UTF-8 charset (HTTP request charset should be UTF-8).
Responses are formatted as JSON. It is strongly recommended to use HTTPS instead of HTTP. HTTP requests are automatically redirected to HTTPS.


= Parameters =


Parameters can be sent by POST or GET. You can mix POST and GET parameters.
= Web Browsing API Reference =


There are some common parameters:
To create web browsing certificates
* '''sharedkey''' is the key assigned to the application.
* '''authkey''' is the user's authorization for the application to use his account.
* '''signature''' is a hash of the request computed using the private key associated to the sharedkey. See [[signature parameter]].


Read the [[API Reference]] to know the parameters expected by each component. Non-required parameters can be omitted from a component call.
== API operations ==
* [[browse/stamp]]: Start a certified browsing session
* [[browse/status]]: Check the status of a web browsing certification job


For additional security, you may include a '''nonce''' parameter with any random value, to get different signatures in repeated operations.


= URL syntax =


API calls usually have the following format:
= Notifications API Reference =


<pre>http://www.safestamper.com/api/{component}?parameter1=value1&parameter2=value2&signature={signature}</pre>
To list and manage user notifications


Some operations do not require a signature, so you can avoid calculating and sending it.
== API operations ==


= Request signature =
* [[notifications]]: List notifications of the user
* [[notification/send]]: Send a new notification
* [[notification/close]]: Close a notification
* [[notification/get]]: Get the notification info.
* [[notification/generatecertificate]]: (deprecated) Generate a new certificate about state of notification
* [[notification/delete]]: Delete notification
* [[notification/tag]]: Set tag to notification
* [[notification/notes]]: Set notes to notification


See [[Signature parameter]]
== API callbacks ==


API operations require a signature of the request. This signature is the HMAC-SHA1 hash of the arguments (sorted by argument name) using the private key associated to your shared key.
If your API key has a [[API Overview#API callbacks|callback URL]], it will receive the following callback events:


= User authorization =
* '''NOTIFICATION_READ''': When the notification recipient has read the notification.
* '''NOTIFICATION_ANSWERED''': When the notification recipient has answered the notification.


'''IMPORTANT:''' If you API keys are linked to your user account, you don't need to perform this process and don't need to include the ''authkey'' parameter in API calls.
These callbacks receive the same JSON as returned by [[notification/get]]


In order to use our services on behalf of a user, you need that user's authorization.
User's authorizations are represented by an '''authkey'''.


You create an authkey with [[createauth]], or [[newuser]] if you are a partner.


After creating an authkey with [[createauth]], the user must authorize your application by visiting '''<nowiki>https://www.safestamper.com/authorize/<AUTHKEY></nowiki>'''
= File API Reference =


This web page can receive a parameter '''r''' with a url where the user will be redirected after authorizing (or rejecting) your authkey.
To create file certificates


<pre>
== API operations ==
https://www.safestamper.com/authorize/c498d3e0-aedb-48fe-82d5-5dec4270318b?r=http%3A%2F%2Fwww.example.com%2Fauthreturn
</pre>


This example will redirect the user to http://www.example.com/authreturn after the authorization process.
* [[file/stamp]]: Upload a file to certificate


= Error handling =
= Signature API Reference =


Errors are returned as HTTP status codes.
To send documents for signature


Common errors include:
== API operations ==


* '''400 (Bad request)''' missing or invalid parameter (response body will indicate the wrong parameter)
* [[signature/sign]]: Send an HTML document for signing
* '''403 (Forbidden)''' sharedkey or signature are not valid
* [[signature/sign-pdf]]: Upload a PDF file for signing
* '''401 (Unauthorized)''' authkey not valid or not authorized
* [[signature/status]]: Check the signing process status of a document
* '''429''' Certificates quota error. The user account does not have certification credits available.
* [[signature/tag]]: Set tag to document
* '''430''' Disk quota error. The user account does not have storage space available.
* [[signature/notes]]: Set notes to document


= API callbacks =
== API callbacks ==
Your API client can have an associated callback URL. Your callback URL will be called for various events.


Your API callback URL will receive a POST request with the following parameters:
If your API client has a [[API Overview#API callbacks|callback URL]], it will receive the following callbacks:
* '''event''': The callback event code
* '''data''': A JSON object with relevant data associated to the event
* '''sharedkey''': Your shared API key
* '''signature''': The callback parameters [[Signature parameter|signature]], calculated with your private API key


Check the [[API Reference]] of each API operation for the different callback events you may receive.
* '''DOCUMENT_SIGNATURE''': When a signer signs the document
* '''SIGNATURE_CERTIFICATE''': When the document signature certificate is ready


= See also =
These callbacks receive the same JSON as returned by [[signature/status]].
* [[API Reference]]
 
 
 
= Partners API =
 
The API operations in this section are only available for designated partners.
 
See [[Partners API]]

Latest revision as of 15:27, 17 October 2023

Authorization API Reference

To create and manage user authorizations.

You don't need to use these operations if your API keys are already linked to your user account.

API operations

  • createauth: Create a pending authorization key that must be authorized by a user.
  • authstate: Check the status of an authkey
  • deleteauth: Delete a user authorization


Certificates API Reference

To list and manage user certificates

API operations

Static Web Page API Reference

To create static web pages certificates

API operations

  • web/stamp: Send URLs for static page certification
  • web/status: Check the status of a certification job

Callbacks

When calling web/stamp you can provide a callback URL:


Web Browsing API Reference

To create web browsing certificates

API operations


Notifications API Reference

To list and manage user notifications

API operations

API callbacks

If your API key has a callback URL, it will receive the following callback events:

  • NOTIFICATION_READ: When the notification recipient has read the notification.
  • NOTIFICATION_ANSWERED: When the notification recipient has answered the notification.

These callbacks receive the same JSON as returned by notification/get


File API Reference

To create file certificates

API operations

Signature API Reference

To send documents for signature

API operations

API callbacks

If your API client has a callback URL, it will receive the following callbacks:

  • DOCUMENT_SIGNATURE: When a signer signs the document
  • SIGNATURE_CERTIFICATE: When the document signature certificate is ready

These callbacks receive the same JSON as returned by signature/status.


Partners API

The API operations in this section are only available for designated partners.

See Partners API