|
|
| Line 1: |
Line 1: |
| = API architecture =
| | This operation can be used instead of the web authorization page, if the application has access to the user's credentials. |
|
| |
|
| Safe Stamper API is a REST-like interface to Safe Stamper services.
| | Usage of this operation is discouraged for security and privacy reasons, so that the application doesn't need to know the user's access credentials. |
|
| |
|
| There are two trust levels for applications using Safe Stamper API.
| | It is preferred to redirect the user to '''<nowiki>https://web.safestamper.com/authorize/<AUTHKEY></nowiki>''', |
| | as explained in [[API Overview#User authorization|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.
| | This operation is only available for designated partners. |
| * '''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 = | | = URL = |
| | | <nowiki>https://www.safestamper.com/api/authorize</nowiki> |
| 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 = |
| | * '''sharedkey''': Your API client shared key |
| | * '''username''': Username or e-mail of Safe Stamper account to authorize |
| | * '''password''': Password of Safe Stamper account |
| | * '''signature''': Parameters signature, as explained in [[Signature parameter]] |
|
| |
|
| Parameters can be sent by POST or GET. You can mix POST and GET parameters.
| |
|
| |
|
| There are some common parameters:
| | = Returns = |
| * '''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.
| | A JSON object with the authorization key status, as returned by [[authstate]]: |
|
| |
|
| For additional security, you may include a '''nonce''' parameter with any random value, to get different signatures in repeated operations.
| | * '''authkey''': Authkey value |
| | * '''authorized''': true/false. |
|
| |
|
| = URL syntax = | | = HTTP Errors = |
|
| |
|
| API calls usually have the following format:
| | * '''403''' Forbidden: the sharedkey or signature are not valid |
| | * '''401''' Unauthorized: the username or password are not valid |
|
| |
|
| <pre>http://www.safestamper.com/api/{component}?parameter1=value1¶meter2=value2&signature={signature}</pre>
| | = Example = |
|
| |
|
| Some operations do not require a signature, so you can avoid calculating and sending it.
| | REQUEST: |
| | | <pre> |
| = Request signature =
| | https://www.safestamper.com/api/authorize |
| | | ?sharedkey=axvmfqn8aex21mxhq5zsj7l482saxfu7j4hh |
| See [[Signature parameter]]
| | &username=apitest |
| | | &password=ddddd |
| 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.
| | &signature=686349c6cbb0fe9094ec26927f4e62306a0263ae |
| | | </pre> |
| = 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.
| |
|
| |
|
| | RESPONSE (actual response has no line breaks or indentation): |
| <pre> | | <pre> |
| https://www.safestamper.com/authorize/c498d3e0-aedb-48fe-82d5-5dec4270318b?r=http%3A%2F%2Fwww.example.com%2Fauthreturn
| | { |
| | "authkey":"0021d81c-e4a5-4869-8384-2fd70cdb58ec", |
| | "authorized":true, |
| | "availableCertificates":50, |
| | "availableNavigations":3, |
| | "userCode":"1612020000541", |
| | "userName":"Api User Test" |
| | } |
| </pre> | | </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]]
| |
This operation can be used instead of the web authorization page, if the application has access to the user's credentials.
Usage of this operation is discouraged for security and privacy reasons, so that the application doesn't need to know the user's access credentials.
It is preferred to redirect the user to https://web.safestamper.com/authorize/<AUTHKEY>,
as explained in User authorization
This operation is only available for designated partners.
URL
https://www.safestamper.com/api/authorize
Parameters
- sharedkey: Your API client shared key
- username: Username or e-mail of Safe Stamper account to authorize
- password: Password of Safe Stamper account
- signature: Parameters signature, as explained in Signature parameter
Returns
A JSON object with the authorization key status, as returned by authstate:
- authkey: Authkey value
- authorized: true/false.
HTTP Errors
- 403 Forbidden: the sharedkey or signature are not valid
- 401 Unauthorized: the username or password are not valid
Example
REQUEST:
https://www.safestamper.com/api/authorize
?sharedkey=axvmfqn8aex21mxhq5zsj7l482saxfu7j4hh
&username=apitest
&password=ddddd
&signature=686349c6cbb0fe9094ec26927f4e62306a0263ae
RESPONSE (actual response has no line breaks or indentation):
{
"authkey":"0021d81c-e4a5-4869-8384-2fd70cdb58ec",
"authorized":true,
"availableCertificates":50,
"availableNavigations":3,
"userCode":"1612020000541",
"userName":"Api User Test"
}