Workbench API
Overview
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 sessions, poll for session status, suspend and stop sessions, 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. Each request is 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:
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.
- 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. - An
admin
token allows that user to see the metadata, suspend, or stop sessions and jobs on behalf of any system user. - 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.