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.

You can test your client’s authorization and other API endpoints in https://api.spreadsheetweb.com/
Previous Create a Web Service Client
Next Types of API Methods