API Reference
Types of Methods
The SpreadsheetWEB RESTful JSON web service supports two types of methods at present:
- Application-level Methods (Endpoint: /Api/Applications)
- These methods access or modify resources protected under a given application, such as calculations, documents, saving data, etc.
- Site-level Methods (Endpoint: /Api/Sites)
- These methods access or modify resources protected under a given site, such as users and application metadata.
Authentication
The SpreadsheetWEB RESTful JSON web service supports an authentication model that operates on OAuth principles, employing a combination of a public and private key to generate an identity for a given client (e.g. the application calling the SpreadsheetWEB web service endpoint).
The Client Identifier is a public key that indicates the identity of the calling client to the server. This can optionally be kept secret to provide for better security and overall management, but our system does employ a brute-force prevention timeout for endpoints attempting to guess the client secret based on the identifier.
The Client Secret is a private key that validates the integrity of the client’s request and should not be exposed under any circumstances to consumers of your application. This secret key should only be known to your application (i.e. the client) and the authorizing server (i.e. SpreadsheetWEB Server).
As a result, it is not recommended to access the web service directly from languages exposed to your consumers.
For example, web applications should make intermediate calls to a web server, which should in turn call the SpreadsheetWEB web service endpoint with the authorization information, rather than directly calling the SpreadsheetWEB web service endpoint from JavaScript, where your Client Identifier and Client Secret would be easily exposed.
Access to these keys exposes your web service applications to unintended or unauthorized usage.
Generating Client Credentials (Application-level)
Client credentials can be generated for an application under the SpreadsheetWEB Control Panel. To create these credentials for a given application, simply access the Edit Application screen and scroll down to the Advanced Features section to find the new Client Key Management module.
This module is currently supported for the following application types:
- Web Services
- Custom Web Pages
- Designer
Note: By default, the only users with the administrative role have access to this module.
Once on the Client Key Management screen, using the Add New button will generate a new credential pair and allow you to choose a Friendly Name, which should identify the target client application that will utilize this set of credentials (e.g. “John’s Calculator”).
In addition, there is a Boolean flag indicating whether this set of credentials includes the ability to Allow Impersonation. Impersonation is a feature that will allow the client (i.e. your application) to indicate to the server (i.e. the SpreadsheetWEB server) a correlated user identity with which to execute the request in some circumstances.
Examples of this include:
- Retrieval of application-stored data records.
- Submission of data to an application as a specific user.
An example and further explanation of Impersonation
Since the SpreadsheetWEB platform organizes and displays data according to factors such as user assignment, role, and group membership, access and retrieval of this data requires the presumption of a specific user identity.
The Client Identifier and Client Secret do not indicate to our server that the calling application is any specific user identity, since it is not providing credentials that correspond to any specific user in the system: it is authorizing as a client but not as a user.
As a result, the server cannot presume that the calling client has access to any specific data. So, by default, when a client (corresponding to a set of credentials without impersonation) attempts to access data from a given application, it will receive no information since the system is not capable of determining what data the client can access based solely on the client-based credentialing.
For this purpose, the Allow Impersonation flag has been included, indicating to the server that the specific set of client credentials can impersonate a user within the site. For example, an application utilizing those credentials could save a record as Cindy (identity) or see the records that Frank (identity) can see.
When allowing this flag, it is increasingly important to prevent and manage access to the client identifier and secret pairing for your application, as exposure of this pairing would effectively allow the same level of exposure to the application’s data as the highest authorized user in the site (i.e. the site administrator), assuming the username was known.
Generating Client Credentials (Site-level)
Unlike the application-level client credentials, the site level credentials are singular for a given site and can be found and modified under the Edit Site page. The only user with direct access to this information is the System Administrator.
All practices referenced for the application-level client credentials are equally relevant, if not more so, to the site level. Unauthorized access to site-level methods can result in unintended user-oriented modifications to the system, such as creation and deletion of users.
Authorized users can regenerate these credentials from the Edit Site page.
Generating an Authentication Token
Rather than relying on constant re-authorization with the service, the consuming client application must call our authorization service to generate an authentication token that will be utilized over subsequent requests to access other resources.
The body of this request will contain both the Client Identifier and Client Secret, which elucidates one of the primary reasons that the actual API endpoint should support (if not require) SSL connections to ensure that the information is adequately protected and encrypted as it’s transferred from the client to the server.
Authentication Token Request
Target Endpoint
POST /Api/Auth/GetToken
Parameters
|
Property Name |
Type |
Is Required? |
Description |
|---|---|---|---|
| ClientIdentifier | String | Required | The identification token for the requested resource. For site-level methods, this will be defined in the site itself. For application-level methods, this will be generated at the application-level. |
| ClientSecret | String | Required | The secret token corresponding to the identifier for access to the request resource. This parameter is private and should not be shared across clients or to unauthorized agents. |
Authentication Token Request Sample
Headers
POST /Api/Auth/GetToken HTTP/1.1 Content-Type: application/json Host: dev7.pagos.com
Body (formatted)
{
"ClientIdentifier": "e2a154c9-dedc-41b5-9a6b-bc31a0312129",
"ClientSecret": "995535e04bd5403aa573cb2be520935b01d2a50ce31a44c9831d3c89fd42988d"
}
Authentication Token Response
|
Property Name |
Type |
Description |
|---|---|---|
| Success | Boolean | Indicated whether or not the authentication request was successful in generating a token based on the provided credentials. |
| AccessToken | String | If the authentication request was successful, the access token to be used for subsequent requests to the restricted resource methods. |
| Issued | DateTime | If the authentication request was successful, the date and time stamp corresponding to the time that the access token was generated. |
| Expires | DateTime | If the authentication request was successful, the date and time stamp corresponding to the time that the access token will expire. Usage of an expired access token will result in failed requests. This should indicate to the client when to generate a new access token. |
| Messages | Array of String | A list of messages, which can be used or captured for diagnostics. When requests are unsuccessful, the reason for the failure will be documented in the Messages list. |
Authentication Token Response Sample (Success)
Headers
HTTP/1.1 200 OK Cache-Control: no-cache, no-store Content-Type: application/json; charset=utf-8
Body (formatted)
{
"AccessToken": "8HwLINPRbwIb_cwc0wvRjD_NOf3FHX4d9s8UyeuSIU41",
"Issued": "2018-04-04T12:49:20.6861539-04:00",
"Expires": "2018-04-04T13:49:20.6861539-04:00",
"Success": true,
"Messages": []
}
Authentication Token Response Sample (Failure)
Headers
HTTP/1.1 200 OK Cache-Control: no-cache, no-store Content-Type: application/json; charset=utf-8
{
"AccessToken": null,
"Issued": null,
"Expires": null,
"Success": false,
"Messages": [
"The supplied credentials are incorrect. Please try again."
]
}
Note: Each failed attempt at authentication will be marked against the consuming client and a timeout will be applied for that client if they fail to authenticate successfully after several consecutive requests.
Attaching the Authentication Token in Subsequent Requests
Once the authentication token has been generated, it will need to be included on subsequent requests to the system.
To do this, simply include the AccessToken as a Bearer token under the Authorization header for subsequent requests:
Headers
Authorization: Bearer 8HwLINPRbwIb_cwc0wvRjD_NOf3FHX4d9s8UyeuSIU41
As per the OAuth guidelines:
To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. (source)
The token should not be shared by the client application after generation and should always be sent over a secure connection.