Workbench API

Workbench | Preview

Overview

Preview feature

This feature is in preview. Preview features are unsupported and may face breaking changes in a future release. Any issues found in the feature will be addressed during the regular release schedule; they will not result in immediate patches or hotfixes.

We encourage customers to try these features and we welcome any feedback via Posit Support, but we recommend that the feature not be used in production until it is in general availability (i.e., officially released as a full feature). To provide feedback, please email your Posit Customer Success representative or sales@posit.co and specify that you are trialing this feature.

The Workbench API allows admins to use Posit Workbench features programmatically. The current feature set includes the ability to launch jobs and sessions, poll for status, suspend and stop sessions, stop jobs, get job output, and check system versions and features. To use the API, create an API token and pass it in supported JSON-based HTTP requests.

See Configuration to enable at least one level of API access to use the API.

All of the APIs require authorization, either an API Token or in some cases they will also work from an authenticated workbench session using the session cookie.

The Workbench API uses the JSON RPC format due to its flexibility to work either over HTTP or websockets, but is currently only supported over HTTP(s) on the main Posit Workbench server. Most requests are made with an HTTP POST method where the body is a JSON object that has method and kwparams properties. Use the method name in both the URL /api/<method-name> and a method property in the JSON object. Certain methods that take no parameters also allow the GET /api/<method-name> format as a shortcut without the JSON body.

Supported APIs

The following links provide reference documentation for each supported API:

• Launch session
• Launch job
• Get sessions/jobs
• Get compute environments
• Get job output
• Stop/suspend session
• Stop job
• Get version

API Tokens

API tokens are managed by an admin using a command line utility that requires sudo privileges. There are three types of tokens supported: user, admin, and super-admin that provide different levels of access to the same set of APIs.

1. A user token is created on behalf of a user, which allows that specific user to launch, query, suspend, and stop their own sessions only.
2. An admin token allows that user to see the metadata, suspend, or stop sessions and jobs on behalf of any system user.
3. A super-admin token allows all operations on behalf of any user, including the ability to impersonate that user and launch a session on their behalf.

Each token can be created with the --read-only option to limit it to non-destructive operations. For example, it allows get session/job but not stop, suspend, or launch.

Tokens can be created with an optional duration using the --duration <num days> option. The default is unlimited.

To generate an API token as an admin on the workbench node, use the command:

rstudio-server generate-api-token <token-type> <token-name> <token-owner-username> [--read-only] [--duration <num days>] [token-args] 

Some examples:

# Create a basic 'user' type token for the system user: ausername
rstudio-server generate-api-token user 'a-user-token' ausername

# Create an 'admin' type token that's read-only for querying session status of any user
rstudio-server generate-api-token admin 'Sample read only admin token' --read-only

# Create a 'super-admin' type token can impersonate any user
rstudio-server generate-api-token super-admin 'Sample super-admin token' ausername

For admin tokens, the token-owner-username is optional.

For flexibility, you may provide the 32 character api-token-secure-key to use on the command line with the --token option:

rstudio-server generate-api-token user 'Sample explicit token' ausername --token 'xe9MU4VzZvJM1uM8WDBulvOEd3RRadlM'

For scripted environments, use --token-env to provide the name of an environment variable that contains the token:

export PWB_API_KEY='xe9MU4VzZvJM1uM8WDBulvOEd3RRadlM'
rstudio-server generate-api-token user 'Also for Jack' jackjohnson --token-env PWB_API_KEY

Posit Workbench only stores an encoded hash of the api-token-secure-key, so if Workbench is creating the token, make sure to record the value that’s output as it’s not possible to recover it.

Configuration

The Posit Workbench API features are disabled by default. You may still generate, list, and revoke api-tokens but they do not work until the server is configured to allow API access.

In rserver.conf add:

# Enable user level tokens
workbench-api-enabled=1

# Enable admin level tokens
workbench-api-admin-enabled=1

# Enable super-admin level tokens
workbench-api-super-admin-enabled=1

Managing tokens

To see details of existing tokens:

rstudio-server list-api-tokens

To remove a token from the database:

rstudio-server revoke-api-token 'token-name'

API format

The Workbench API uses JSON RPC format. The version and id fields are not yet implemented.

Request format

{
   "method": "method_name",
   "kwparams": {
      "param1": paramVal,
      "param2": paramVal
   }
}

Success response format

Each of the JSON RPC requests return an HTTP 200 status code on success and a JSON RPC result:

{
   "result": ...
}

Error response format

There are two levels of errors reported. HTTP errors include: 401 for permission denied, and 502 or 503 for server problems. Additionally, the request may be blocked by an intermediate proxy layer that returns its own 40x or 50x errors.

For errors that occur during request processing, a 200 HTTP status is returned with a JSON RPC error:

{
   "error": {
      "code": 123,
      "message": "A message describing the error"
   }
}

These errors include problems associated with the user’s account, configuration problems on the server node, or resource limitations that prevent fulfilling the request.

Examples

Example for launch_session

#!/bin/bash
method="launch_session"

# Replace with your 32 character API token
apiToken=<api-token-key>

# Replace the username value with a valid user account on the system
# Additional launch_parameters required for other session types.
paramsJson=', "kwparams": {"launch_parameters":{"name":"Test RStudio Session","cluster":"Local"}, "username":"replace-this-user-name"}'

# Replace with your Posit Workbench server URL
workbenchServerUrl="http://localhost:8787"

curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer $apiToken" \
     -d "{\"method\":\"$method\" $paramsJson}" \
     "$workbenchServerUrl/api/$method" 

Example for get_session

This example passes no parameters to get all properties, from all sessions.

#!/bin/bash
method="get_session"

# Replace with your 32 character API token
apiToken=<api-token-key>

# Replace with your Posit Workbench server URL
workbenchServerUrl="http://localhost:8787"

curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer $apiToken" \
     -d "{\"method\":\"$method\"}" \
     "$workbenchServerUrl/api/$method" 

Example for stop_session

#!/bin/bash
method="stop_session"

# Replace with your 32 character API token
apiToken=<api-token-key>

paramsJson=', "kwparams": {"session_ids":"93022e28"}'

# Replace with your Posit Workbench server URL
workbenchServerUrl="http://localhost:8787"

curl  -H "Content-Type: application/json" \
      -H "Authorization: Bearer $apiToken" \
      -d "{\"method\":\"$method\" $paramsJson}" \
      "$workbenchServerUrl/api/$method" 

Example for get_compute_envs

#!/bin/bash
method="get_compute_envs"

# Replace with your 32 character API token
apiToken=<api-token-key>

# Replace with your Posit Workbench server URL
workbenchServerUrl="http://localhost:8787"

curl  -H "Content-Type: application/json" \
      -H "Authorization: Bearer $apiToken" \
      -d "{\"method\":\"$method\"}" \
      "$workbenchServerUrl/api/$method" 

Troubleshooting

Enable debug logging for the [@rserver] target in logging.conf that logs to rserver.log in /var/log/rstudio/rstudio-server, or the stderr log target by default, or use the /admin URL to turn on debug logging temporarily while testing the api. Each attempt at an API access includes details about the token and URL, used to help diagnose problems. Ensure the appropriate api-access levels are enabled in the configuration.