Securo API Docs (v1)

The Securo API allows to easily integrate the process of certification through trusted timestamping into any application through a RESTful HTTP interface. With the Securo API you will have access to the same certified timestamping authority as we use in our products: Securo Mobile and Easytimestamping.

The API can be accessed at https://api.securo.it.

In each request, the API version can be omitted to always use the latest version or it can be specified as part of the route, e.g. https://api.securo.it/v1/.

Securo API libraries

We have made available the following libraries so you can skip reading this documentation and start developing right away:

Securo API for Python securo-api-python example code
Securo API for PHP securo-api-php example code

If you need to access the Securo API using other languages or need an in depth look at how the API works please continue reading.

Authentication

Authentication is performed through a classic stateless HMAC-SHA256 signature process: each HTTP request that needs authentication (such as the timestamping request) must carry an apiSignature parameter that represents the HMAC-SHA256 signatures of the route and request parameters, sorted alphabetically. Each user has access to its API key (the userId) and an API secret that is used as a key for the signature. For example, given a user with userId and API secret:

userId: 57c926be-34c4-4daa-8602-5c0b09df6202
API secret: 8e7a00f1daf1c2b7015459dd686856c2

a timestamping request will be:

https://api.securo.it/user/57c926be-34c4-4daa-8602-5c0b09df6202/proof/

with POST parameters:

digest=6f0378f21a495f5c13247317d158e9d51da45a5bf68fc2f366e450deafdc8302
apiSignature=621e285d1eb6145242a483d16aa0f0355f0d263b85a424da52bb40c5c7473a23

where the apiSignature is the HMAC-SHA256 of the the string:

/user/57c926be-34c4-4daa-8602-5c0b09df6202/proof/?digest=6f0378f21a495f5c13247317d158e9d51da45a5bf68fc2f366e450deafdc8302

To access your API key (userID) and API secret go to http://easytimestamping.com/#useraccount.

Authentication with OpenID

Login and registration in Securo Mobile for Android and iPhone are performed through OpenID. The OpenID provider callback will POST to the /user/ route that generates a sessionToken that must be used in subsequent api calls to authenticate the access to the specific resource (and/or requested operation).

More info on the authentication flow for web, iPhone and android.

Since OpenID login requires user intervention, it is not well suited for automated testing. With the securo API, OpenID login can be simulated by with a POST request to /user/ passing the parameter &remoteTest=, that will login a test user.

** All routes market as authenticated need the sessionToken passed as HTTP parmeter **

A note about Http status codes

A successfull API call will return an Http status code 200. In case of failure, a json object is returned. The Http status code, toghether with the returned json object, can be used to understand the reason for the failure and the message usually contains more information about the cause of the failure.

{ "status": "failure", "code": 401, "message": "Not enough timestamps." }

API summary

GET /user/:userId Retrieve info about a specific user.
POST /user/ Register (i.e. create a new user resource) or login (i.e. obtain a new sessionToken).
GET /proof/:proofId Retrieve details about a specific proof.
POST /user/:userId/proof/ Create a new proof for the specified user.
POST /user/:userId/proofs/ Recharge user proofs.
GET /user/:userId/proofs Retrieve all proofs created by a user.
GET /proof/:proofId/:field Retrieve specific data about a proof.
POST /proof/verify/ Verify an RFC3161 trusted timestamp.

GET /user/:userId

Retrieve info about a specific user. Each user is identified by a UUID.

Route parameters:

Examples:

https://api.securo.it/user/57c926be-34c4-4daa-8602-5c0b09df6202

Will return:

{
    "status": "success", 
    "uri": "https://api.securo.it/user/57c926be-34c4-4daa-8602-5c0b09df6202", 
    "userId": "57c926be-34c4-4daa-8602-5c0b09df6202"
    "profile": {
        "displayName": "a.test", 
        "email": "a.test@example.com", 
        "googleUserId": "1635144296171389362695", 
        "identifier": "https://www.google.com/profiles/1635144296171389362695", 
        "name": {
            "familyName": "Testerson", 
            "formatted": "A Testerson", 
            "givenName": "A"
        }, 
        "preferredUsername": "a.test", 
        "providerName": "Google", 
        "url": "https://www.google.com/profiles/1635144296171389362695", 
        "verifiedEmail": "a.test@example.com"
    },
    "proofs": {
        "completed": "83", 
        "remaining": "585", 
        "uri": "https://api.securo.it/user/57c926be-34c4-4daa-8602-5c0b09df6202/proofs/"
    },
    "badges": [
        2, 
        3
    ], 
}

Http status codes:

Notes:

Each user is only authorized to access his own information.

POST /user/

This is used to register (i.e. create a new user resource) or login (i.e. obtain a new sessionToken). This route should is usually called as an openId callback, exept when testing using remoteTest

Route parameters:

Http parameters:

Examples:

The POST request:

https://api.securo.it/user/?remoteTest=

will return:

{
    "status": "success",
    "expiration": 0,
    "sessionToken": "045ba7a52eacb814d2860417f602c438",
    "user": { <user object (same as with GET /user/>) }
}

Http status codes:

Notes:

Having a POST request both create a new user and perform a login (thus creating a new session) is not exactly RESTful. We decided that login and registration are the same (i.e. a user that logs in for the first time is doing the registration) so this is the only choice.

GET /proof/:proofId

Retrieve details about a specific proof. Proofs are public, thus do not require authentication.

Route parameters:

Http parameters:

Examples:

https://api.securo.it/proof/f6150f59-aa5f-4a2d-9bf3-7432f13414e1?decodedTsr=

will return:

{
    "date": "1326905377", 
    "digest": "f3b15e71579dba39f0ba2adc476c73584bd49fb10cdc6b653cbe8215d7c07fad", 
    "id": "f6150f59-aa5f-4a2d-9bf3-7432f13414e1", 
    "name": "f3b15e71579dba39f0ba2adc476c73584bd49fb10cdc6b653cbe8215d7c07fad", 
    "pdfUrl": "https://api.securo.it/proof/f6150f59-aa5f-4a2d-9bf3-7432f13414e1/pdf", 
    "sdigest": "03e42dca9b4134950a19c6739b97b85aacaa4801ebbc3492e8048f3ac7d46d84f9c89e84ab3e24ba1eb7172affc3524a01d71714c587ac135ba395de099b81995871e3b7994515638ba1813c88d5a51b94aa4d5c3535acbc1cdfe29a860a85229a59a4a911449e3575000ceb1c850ff4cf22b0c8c0f57185c055e36c13711639e0bcbddf3fe6d11af47af7eb01643cf1cbb8306e8e3fcbf6474efeb25c9aacbb0a1e85e6114e63ade723eaa15d5d0b514f9591468f1a35f7ce6b83eb407129c0f9df9d92330d014b0db465729d10ce19306a8e62cf256d8fbac4f1761ac04e8de47e45af07c6feec94ca18fc7870928dc6949abc9ed1d39538da94684764042e", 
    "status": "success", 
    "tsrUrl": "https://api.securo.it/proof/f6150f59-aa5f-4a2d-9bf3-7432f13414e1/tsr", 
    "uri": "https://api.securo.it/proof/f6150f59-aa5f-4a2d-9bf3-7432f13414e1", 
    "userId": "347a6100-88af-42e9-b643-0f20ada8bb09"
    "timeStampResponse": {
        "accuracy": "unspecified seconds, 0x01F4 millis, unspecified micros", 
        "digest": "6f0378f21a495f5c13247317d158e9d51da45a5bf68fc2f366e450deafdc8302", 
        "extensions": "", 
        "failureInfo": "unspecified", 
        "hashAlgorithm": "sha256", 
        "nonce": "0x9C8FAF9E0C4FF3EC", 
        "ordering": "no", 
        "policyOid": "1.3.6.1.4.1.23624.1.1.50.3.0", 
        "serialNumber": "0x4D53901485E8", 
        "status": "Granted.", 
        "statusDescription": "unspecified", 
        "statusInfo": "", 
        "timeStamp": "Aug  1 18:49:27.519 2011 GMT", 
        "timeStampResponsePem": "<Pem encoded RFC3161 compliant trusted timestamp>",
        "tsa": "DirName:/C=CZ/CN=I.CA - Time Stamping Authority, TSS/TSU 3, 12/2009/O=Prvn\\xC3\\xAD certifika\\xC4\\x8Dn\\xC3\\xAD autorita, a.s./OU=I.CA - Accredited Provider of Certification Services", 
        "tsrVersion": "1", 
        "tstInfo": ""
    }, 
}

Http status codes:

Notes:

POST /user/:userId/proof/

Create a new proof for the specified user

Route parameters:

Http parameters:

Examples:

The post request:

https://api.securo.it/user/57c926be-34c4-4daa-8602-5c0b09df6202/proof/
    ?digest=6f0378f21a495f5c13247317d158e9d51da45a5bf68fc2f366e450deafdc8302
    &decodedTsr=
    &sendEmail=

will return a proof object (see GET /proof/ route) and will send an email to the user communicating a successfull proof creation.

During development and for testing purposes, the cheap switch can be set to true and your credit will not be decreased (but the generated proof has no legal value):

https://api.securo.it/user/57c926be-34c4-4daa-8602-5c0b09df6202/proof/
    ?cheap=true
    &digest=6f0378f21a495f5c13247317d158e9d51da45a5bf68fc2f366e450deafdc8302

Http status codes:

Notes:

The cheap switch is particularly useful during development. It is good practice to automatically check (with a pre-deploy hook for example) that the cheap switch is disabled before deploying your application.

POST /user/:userId/proofs/

Recharge user proofs.

Route parameters:

Http parameters:

* productId: the certification package id. Can be: small, medium, large, xlarge. * couponCode (optional): a code used to access discounts

The signature and signedData parameters still need to be defined for the iphone app store. Do not use them for now, but note that all recharges will be accredited to the "test" user.

Examples:

Recharge with a small package.

https://api.securo.it/user/57c926be-34c4-4daa-8602-5c0b09df6202/proofs/
    ?productId=small

will return:

{
    "status": "success",
    "user": { <user object (same as with GET /user/>) }
}

Http status codes:

GET /user/:userId/proofs

Retrieve all proofs created by a user.

Route parameters:

Examples:

The get request:

https://api.securo.it/user/57c926be-34c4-4daa-8602-5c0b09df6202/proofs

will return:

{
    "status": "success",
    "proofs": {
        "proofId-1": { <proof object (same as with GET /proof/:id route>) },
        "proofId-2": { <proof object (same as with GET /proof/:id route>) },
        ...
        "proofId-n": { <proof object (same as with GET /proof/:id route>) }
    }
}

Http status codes:

GET /proof/:proofId/:field

Retrieve specific data about a proof. This route is useful for retrieving the tsr file or a printable pdf version of the proof.

Note that these routes are readily available in any proof object. See tsrUrl and pdfUrl in GET /proof/ route.

Route parameters:

Examples:

Retrieve the RFC3161 compliant trusted timestamp:

https://api.securo.it/proof/2659f26a-d223-499f-9353-4ffa08463096/tsr

Retrieve a printable pdf representing the proof:

https://api.securo.it/proof/2659f26a-d223-499f-9353-4ffa08463096/pdf

Http status codes:

POST /proof/verify/

Verify an RFC3161 trusted timestamp, given a message digest.

Http parameters:

Examples:

This simple script demonstrate usage of the /proof/verify/ route

tsrdata=$(openssl enc -base64 -in file.tsr)
curl -X POST --data 'tsrdata='$tsrdata'&digest='$digest https://api.securo.it/proof/verify/'

The result of the verification is contained in the result object of the returned json. In case of unsuccessful verification, it will return:

{
    "result": {
            "status": "failure",
            "message": "Digest mismatch",
            "code": 2
    },
    "status": "success",
}

In case of successfull verification:

{
    "result": { "status": "success" },
    "status": "success",
}

Http status codes: