SuperReceipt provides two options to access data securely

The SuperReceipt API provides two methods to access data securely. Choose your method based on the 'environment' of your application:

• 'trusted' environment: the application that accesses the data is resident on a protected server without a customer-facing element.
• 'non-trusted' environment: the application that accesses the data is customer-facing. This includes a web app running in a browser or a mobile application.

From the perspective of the API, we will call these environments in the remainder 'trusted' and 'non-trusted' clients, but note that 'client' here can also mean a server-hosted application.

Secure acccess for trusted clients

This is the easiest to secure. We provide a simple authentication method via an API key that is unique to your account. Your protected server adds an apikey header to each HTTPS request to the SuperReceipt API. Note that SuperReceipt only supports HTTPS access. You are responsible for keeping your API key securely stored and for storing the data obtained from SuperReceipt to prevent unauthorized access. If your API key would be compromised, email info@sophatar.com to invalidate the current API key and issue a new one. At your request a transition period can be provided druing which both keys are valid, so you have enough time to update your infrastructure. Sophatar may also periodically inform you that API keys will be updated to guarantee overall security of the API, even when no breach has occurred. In this case sufficient upfront notice will be given and a transition period included to allow you to update.

Secure access for non-trusted clients

The previous method requires you to access the SuperReceipt API from your backend infrastructure. This may become unwieldy for large volumes of receipt data when you develop a customer-facing application, e.g. a web app or a mobile app that utilizes data from SuperReceipt. In this case it may better to access SuperReceipt data directly from the customer-facing software. You should NOT use an API key in this case as your application may be reverse-engineered. This could cause an attacker to develop a rogue application that uses your API key to retrieve data.

For this scenario you should access the API via an access token. Access tokens on the SuperReceipt API have a limited lifetime, currently 1 hour, after which they automatically become invalid.

You should implement a route on your backend server which clients can access to obtain a new access token. You are responsible for making sure only authenticated clients (via your login on the client) can access this route. With the access token, your clients can then directly obtain data from the SuperReceipt API, avoiding the need to store data on your server.

The workflow is documented below, and is compliant with the OAuth2 'client credential grant' flow, see this reference.

Implementation

1. To obtain an access token, your server shall implement a POST request with a client_id and client_secret combination that is provided to you as part of your account activation. These two parameters identify you and your 'application' to the SuperReceipt API. These parameters should be securely stored on your server and never sent to the non-trusted environment. Provide a route on your server that calls below route on the SuperReceipt API so that your client can request this access token.

   The equivalent curl command on the SuperReceipt API to request an access token is: curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'hhttps://api.sophatar.com/superreceipt/oauth2/token -d 'grant_type=client_credentials&client_id={your-client-id}&client_secret={your-client-secret}

   The server will respond with the access token, its intended use (as a bearer token) and lifetime (currently set to 3600 seconds or 1 hour): { "token_type": "bearer", "access_token": "{access-token}", "expires_in": 3600 }

2. The access token is used as a 'bearer token' for calls to the SuperReceipt API. It means there is no further need for user or app credentials during the limited time the token is valid. Your client can call all routes on the SuperReceipt by placing a header: Authorization: Bearer {access-token} where {access-token} is the value obtained in the prior step. This authorization header replaces the apikey header. The content of all API responses is identical to when using the API key authorization method.

3. When the token is no longer valid, the SuperReceipt API will return a message stating invalid credentials were provided. At that time you shall re-execute step 1 (possibly only after verifying your user is still authenticated in your client). When you request a new access token, prior access tokens are NOT invalidated - they only invalidate when they expire. This allows you to work with many client instances that each use different access tokens so you do not need to centrally store or synchronize them.