1. Overview

Spotfire Server REST API for Automation Jobs execution management.

1.1. Version information

Version : 1

1.2. Tags

  • automation-services-controller : Automation Services Controller

2. Authentication and authorization

The API uses the OAuth 2.0 protocol for authentication and authorization, with the Spotfire Server itself as Authorization Server. Authentication and authorization can also be delegated to an external Authorization Server through the use of Token Exchange.

Note: The API does not use HTTP sessions so there is no need to maintain session cookies.

Note: All communication should always be done over HTTPS when using OAuth 2.0.

2.1. Basic steps

  1. Register an API client using the register-api-client command to obtain client credentials.

    When registering the client you specify what type of client it is, what grants and scopes the client should be able to use etc.

  2. Obtain an access token using one of the following alternatives

    • To use the Authorization Code grant follow the instructions in section 4.1 of RFC 6749.

    • To use the Client Credentials grant follow the instructions in section 4.4 of RFC 6749.

    • To use a Refresh Token follow the instructions in section 6 of RFC 6749.

    • To use the Token Exchange grant follow the instructions in section 2 of RFC 8693.

      Additional information on how to get the access token

    • The OAuth 2.0 Authorization Server Metadata (RFC 8414) can be retrieved from: http[s]://<host>[:<port>]/spotfire/.well-known/oauth-authorization-server

    • The Authorization Endpoint can be accessed at: http[s]://<host>[:<port>]/spotfire/oauth2/auth

    • The Token Endpoint can be accessed at: http[s]://<host>[:<port>]/spotfire/oauth2/token

    • When calling the Token Endpoint the client must authenticate using either the client_secret_post or the client_secret_basic scheme (determined when registering the client) as described in section 2.3.1 of RFC 6749, using the credentials obtained when registering the client (unless the client is a public client to which no credentials have been issued). Public clients _must include the client_id parameter.

    • The initial request (to the Authorization Endpoint in the case of the Authorization Code grant, or to the Token Endpoint in the case of the Client Credentials or the Token Exchange grant) must include any and all scopes required to access the services that the client intend to access (see the documentation of each service for details).

  3. Include the access token in all requests to the API, in an Authorization header as described in section 2.1 of RFC 6750.

    • The access token has a limited lifetime, after which a new token must be obtained by repeating step 2.

    • An access token is only valid for the services and operations described in the scope parameter provided when obtaining the access token. The available scopes are described in the documentation for each service.

2.2. Additional information

  • Four client profiles are supported: other, web, native and user_agent. The profile other should be used by a typically headless application performing requests on its own behalf. The profile web should be used by a server-side web application performing requests on behalf of an end-user. The profile native should be used by a native client, such as an iOS or Android app, performing requests on behalf of an end-user. The profile user_agent should be used by a client-side (JavaScript) web application, performing requests on behalf of an end-user.

  • The Authorization Code, Client Credentials, Refresh Token and Token Exchange grants are supported.

  • Clients with profile web, native or user_agent can only use the Authorization Code, Refresh Token and Token Exchange grants. Clients with profile other can only use the Client Credentials and Token Exchange grants.

  • Refresh tokens MAY be issued to allow access also when no end-user is present (useful when for example performing periodic uploads or similar). To request a refresh token to be issued the scope offline should be included in the request. For more information see section 1.5 of RFC 6749.

    • Refresh tokens that are no longer needed SHOULD be revoked, as described in RFC 7009.

  • Public clients (clients without client credentials) MUST use PKCE (RFC 7636). Confidential clients SHOULD use _PKCE.

  • Native clients can use any of the three ways of receiving the response listed in section 7 of RFC 8252.

    • To use Private-Use URI Scheme Redirection a custom URI scheme must be registered when registering the client.

    • To use Claimed "https" Scheme URI Redirection an authorized redirect URI must be registered when registering the client.

    • Loopback Interface Redirection is supported for all native clients. The scheme must be http. The host must be either 127.0.0.1 (IPv4) or [::1] (IPv6). The path can be either / or /auth. The port is variable.

  • Native clients SHOULD adhere to the guidelines outlined in OAuth 2.0 for Native Apps (RFC 8252).

  • All clients SHOULD implement support for OAuth 2.0 Authorization Server Issuer Identification (RFC 9207).

2.3. Using an external Authorization Server

The Token Exchange grant can be used to authorize use of the Spotfire Server API using an external Authorization Server. The API client will first obtain a subject token from the external Authorization Server and then, through Token Exchange towards the Authorization Server of the Spotfire Server, exchange that token for an access token that can be used with the Spotfire Server API. The subject token issued by the external Authorization Server MUST follow the format of RFC 9068 (JWT Profile for OAuth 2.0 Access Tokens) and the requirements described further down.

2.3.1. Requirements

The Token Exchange grant must be explicitly enabled by configuring the Spotfire Server to trust tokens issued by the external Authorization Server. Configuration is done using the config-rfc-9068-token-exchange-authenticator command. The most basic configuration only requires setting the URI to the OAuth 2.0 Authorization Server Metadata document of the external Authorization Server. The metadata document MUST contain an issuer and a jwks_uri (with the keys needed to verify subject token signatures).

Requirements on the Token Exchange request

  • The value of the resource parameter MUST be the public address of the Spotfire Server.

  • The audience parameter MUST NOT be included.

  • The scope parameter MUST be included.

  • The value of the requested_token_type parameter MUST be urn:ietf:params:oauth:token-type:access_token.

  • The value of the subject_token parameter must adhere to the requirements described below.

  • The value of the subject_token_type parameter MUST be urn:ietf:params:oauth:token-type:jwt.

  • The actor_token and actor_token_type parameters MUST NOT be included.

  • If the client is a public client then the client_id parameter MUST be included. Otherwise the client MUST authenticate.

Requirements on the subject token

  • Must adhere to the requirements of RFC 9068 (JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens).

  • The aud claim MUST include the Spotfire Server Token Endpoint URI.

  • The token SHOULD contain a may_act claim.

  • If the token contains a may_act claim then the value of the client_id sub-claim MUST be client ID of the client using the token.

  • The token SHOULD contain a scope claim.

  • If the token contains a scope claim then all scopes requested (through the scope parameter) MUST also be present in the scope claim.

3. API Endpoint URLs

All API services can be accessed at the following location, where ServicePath is one of the entries in the Resources listing below:

http[s]://<host>[:<port>]/spotfire/api/rest/as/<ServicePath>

Example:

https://example.com:8443/spotfire/api/rest/as/job/start-content

You can download the Open API Specification (OAS) for this REST API as a JSON file from the Spotfire Server at http[s]://<host>[:<port>]/spotfire/api/v2/api-docs?group=as. This OAS file can be accessed at this location by all authenticated users (unless disabled through configuration). The OAS file can be used to generate client stubs, which will contain all types and methods that can be used with the API.

You can also browse the OAS for this REST API using the Swagger UI, available at http[s]://<host>[:<port>]/spotfire/api/swagger-ui.html?urls.primaryName=as

4. Resources

4.1. Automation-services-controller

4.1.1. Get status of an Automation Services job

GET /job/status/{jobId}
Description

This method returns the status of an Automation Services job

Parameters
Type Name Description Schema Example

Path

jobId
required

The Automation Services job ID

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Responses
HTTP Code Description Schema

200

OK

ExecutionStatus

404

Job not Found
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.rest.automation-services-job.execute

4.1.2. Abort an ongoing Automation Services job

POST /job/abort/{jobId}
Description

This method aborts an ongoing Automation Services job based on its job ID

Parameters
Type Name Description Schema Example

Path

jobId
required

The ID of the Automation Services job to abort

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Query

reason
optional

A text describing the reason for aborting the job

string
Responses
HTTP Code Description Schema

200

Job Aborted

ExecutionStatus

404

Job not Found
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.rest.automation-services-job.execute

4.1.3. Start an Automation Services job from XML

POST /job/start-content
Description

This method starts an Automation Services job from its XML definition

Parameters
Type Name Description Schema Example

Query

path
optional

The path

string

Body

Body
required

The Automation Services Job definition

string
Responses
HTTP Code Description Schema

200

Job Created

ExecutionStatus
Consumes

  • application/xml

Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.rest.automation-services-job.execute

4.1.4. Start an Automation Services job from a library file

POST /job/start-library
Description

This method starts an Automation Services job from a library file. The identity of the file can be provided using either library path or library ID (GUID). Note that the API client must have sufficient library permissions to access the library item.

Parameters
Type Name Description Schema Example

Query

id
optional

The library ID of the Automation Services job

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Query

path
optional

The library path of the Automation Services job

string
Responses
HTTP Code Description Schema

200

Job Created

ExecutionStatus
Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.rest.automation-services-job.execute

5. Definitions

5.1. ExecutionStatus

Name Description Schema

statusCode
required

Status
Example : "Canceled"

ExecutionStatusCode

message
required

Message
Example : "Canceled per user request"

string

jobId
required

The GUID of the job
Example : "948c87c6-a271-44a0-b7db-cccfa08fa720"

string

5.2. ExecutionStatusCode

Enum value Schema

NotSet

string

Queued

string

InProgress

string

Finished

string

Failed

string

Missing

string

Busy

string

Canceled

string

6. Security

6.1. spotfire-api-oauth2

Type : oauth2
Flow : application
Token URL : /spotfire/oauth2/token

Name Description

api.rest.automation-services-job.execute

Execute and abort Automation Services jobs

7. Common Responses

HTTP Code Description Reason

401

Not Authenticated

The client has not been authenticated

403

Not Authorized

The client is not authorized to access the requested resource

500

Internal Server Error

Something went wrong when the processing the request

8. Configuration

The API is enabled by default. To disable it or to make other configuration changes, use the config-web-service-api command. For more information see the section Configuration using the command line of the Spotfire© Server and Environment Installation and Administration manual.

9. Additional resources

For more information please refer to these resources:

  • The Spotfire Community.

  • The SDK zip contains an example written in C# for how to call the automation services API and on how to authenticate with the Spotfire Server. For more information on the example see the readme.txt in the example: <SDK.zip>\Examples\Integration\SpotfireDeveloper.ServerApiExample