Adminwiki: 1 revision imported

2023-10-17T11:27:26Z

1 revision imported

← Older revision	Revision as of 07:27, 17 October 2023
(No difference)

api>Admin: /* User authorization */

2021-08-10T11:17:08Z

User authorization

New page

= 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 [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:
* 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]

= 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 [https://www.safestamper.com/contact 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 <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.

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:

<pre>http://www.safestamper.com/api/{component}?parameter1=value1&parameter2=value2&signature={signature}</pre>

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

= Request signature =

See [[Signature parameter]]

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 '''<nowiki>https://www.safestamper.com/authorize/<AUTHKEY></nowiki>'''

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

<pre>
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.

= 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 parameter|signature]], calculated with your private API key

Check the [[API Reference]] of each API operation for the different callback events you may receive.

= See also =
* [[API Reference]]

API Overview - Revision history

Adminwiki: 1 revision imported

api>Admin: /* User authorization */