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 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 /connect/token
Parameters
| Property Name | Type | Is Required? | Description |
| client_id | 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. |
| client_secret | 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. |
| grant_type | String | Required | The value has to be set to client_credentials because that is what is supported by web service clients that are created for this specific use case. |
Authentication Token Request Sample
Headers
POST {identity.url}/connect/token
Content-Type: application/x-www-form-urlencoded
Body
client_id=2325017296885280204 &client_secret=567780199036516938 &grant_type=client_credentials
Authentication Token Response
| Property Name | Type | Description |
| access_token | String | If the authentication request was successful, the access token to be used for subsequent requests to the restricted resource methods. |
| expires_in | Integer | If the authentication request was successful, the amount of time that an access token is valid (in seconds). Usage of an expired access token will result in failed requests. This should indicate to the client when to generate a new access token. |
| token_type | String | Indicates the token type value. The only type that the SpreadsheetWEB Hub platform supports is bearer. |
| scope | String | Indicates context in which that token may act. |
Authentication Token Response Sample (Success)
Headers
HTTP/1.1 200 OK Cache-Control: no-cache, no-store, max-age=0 Content-Type: application/json; charset=utf-8
Body
{
"access_token": "c19odWJfY4KoSpF5UCZbPFaSJ6l5RGDGGudH ",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "pagos_hub_api"
}
Authentication Token Response Sample (Failure)
Headers
HTTP/1.1 400 Bad Request Cache-Control: no-cache, no-store, max-age=0 Content-Type: application/json; charset=utf-8
Body
{
"error": "invalid_client"
}
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 access_token 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.