API Overview
API architecture
Safe Stamper API is a REST-like interface to Safe Stamper services.
There are two trust levels for applications using Safe Stamper API.
- 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 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:
- 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 Safe Stamper contact form
Arena sandbox environment
There is a testing environment available at http://arena.safestamper.com.
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.
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 Safe Stamper contact form. When we activate your api keys, you can start testing the API.
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
Accessing the API
Safe Stamper API Services are accessible via a REST-like interface. The interface is rooted at http://www.safestamper.com/api/ for production services and http://arena.safestamper.com/api/ for the arena environment.
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.
There are some common parameters:
- 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.
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:
http://www.safestamper.com/api/{component}?parameter1=value1¶meter2=value2&signature={signature}
Some operations do not require a signature, so you can avoid calculating and sending it.
Request signature
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.
User authorization
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.
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 https://www.safestamper.com/authorize/<AUTHKEY>
This web page can receive a parameter r with a url where the user will be redirected after authorizing (or rejecting) your authkey.
https://www.safestamper.com/authorize/c498d3e0-aedb-48fe-82d5-5dec4270318b?r=http%3A%2F%2Fwww.example.com%2Fauthreturn
This example will redirect the user to http://www.example.com/authreturn after the authorization process.
Error handling
Errors are returned as HTTP status codes.
Common errors include:
- 400 (Bad request) missing or invalid parameter (response body will indicate the wrong parameter)
- 403 (Forbidden) sharedkey or signature are not valid
- 401 (Unauthorized) authkey not valid or not authorized
- 429 Certificates quota error. The user account does not have certification credits available.
- 430 Disk quota error. The user account does not have storage space available.
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:
- 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, calculated with your private API key
Check the API Reference of each API operation for the different callback events you may receive.