API Authentication and Calculations

Authenticate an external client and call a SpreadsheetWeb workbook calculation through the Hub API. This lesson follows the full workflow from preparing the Excel model and publishing an API application to obtaining an access token and reading calculated outputs.

Prepare stable workbook references

Identify every input the external system will set and every output it must receive. Assign named ranges to those cells or blocks whenever possible.

Named ranges provide a stable API contract even if rows, columns, or worksheets are inserted later. A consistent naming convention, such as distinguishing input and output ranges, also makes request mapping easier to understand, although SpreadsheetWeb does not require a specific prefix.

A range can represent one cell, a list, or a two-dimensional table. The API uses a two-dimensional value structure so the same request format can handle each shape.

Create a web service client

1. Open Web Services in the SpreadsheetWeb Hub workspace.
2. Select Create New Client.
3. Enter a name that identifies the consuming system, such as a Postman test client.
4. Grant only the application and data permissions the integration requires.
5. Save the client and record its client identifier and client secret.

Treat the client secret as a credential. Do not place it in client-side code, public repositories, screenshots, or shared documentation.

Publish the workbook as an API application

Create a new application, upload the prepared workbook, and publish it. The initial work-in-progress transaction cannot be called externally until it is published.

Record the workspace ID and application ID from their respective Hub pages. These identifiers tell the calculation endpoint which workbook application to execute.

Request an OAuth access token

Send a POST request to the token endpoint using the client credentials flow:

• Use the web service client's identifier and secret.
• Set the grant type to client_credentials.
• Send the form using the content type required by the token endpoint.

The response contains an access token and expiration information. Request a new token after the current token expires. Add the active token to subsequent API calls as a Bearer token in the authorization header.

Build the calculation request

The calculation payload identifies the workspace and application, then supplies input and output collections.

Each input reference contains a named range or cell reference and its value matrix. Optional cell-value properties can control behavior such as overwriting a formula or explicitly setting a value type; most normal requests can rely on the workbook's existing formulas and types.

Outputs are the range references that should be returned after calculation. Named ranges are preferred because direct cell references are more likely to break when the workbook structure changes.

Read the calculation response

Submit the authenticated request to the calculation endpoint. The response contains a range object for every requested output, including the returned cell values. Single cells, lists, tables, and grids all use the same range-oriented structure.

Validate the first integration request against a known workbook scenario before adding more inputs, outputs, save operations, or other API features.