Accessing Content via API

API Keys

API keys allow you to programmatically access content on Posit Connect and use the Connect Server API. They are a substitute for logging in to Connect to publish or access content.

All account types are able to use API keys, though the set of allowable operations varies according to the type of account and content sharing settings. Some example uses:

  • Users with administrator accounts can use the Connect Server API to understand which users have logged into Connect.
  • Users with publisher accounts can use rsconnect-python to publish Shiny applications to Connect.
  • Users with viewer accounts can write code to download data sets from a pin published by one of their colleagues.

An API key is associated with the user who creates it. API keys are not associated with any specific content item. API keys allow access to the Connect Server API and also to published content. An API key is granted a user role equal to or less than your own role. Your API key has the same rights and permissions as you, subject to role restrictions. If you are able to visit some content using the Connect dashboard, your API key can be used to programmatically interact with that same content.

You may create an API key with a more restrictive role than you by designating the role at creation time. For example, administrators can create “publisher” API keys which are not permitted to perform administration activities. A publisher can use a “viewer” API key to call a hosted Plumber API; that same key cannot publish content.

Note

You may not create a key with a more permissive role than your own. You may not modify the role of a key after it is created. If your user account is ever demoted to a more restricted role (e.g., from administrator to publisher), any existing keys with a more permissive role belonging to your account are effectively restricted to your new role.

It is a recommended practice to create a new API key for each external tool that needs access to content hosted on Connect, and to give each key a name that helps you identify the tool that uses it. When the tool no longer needs access, or if you cannot trust the key at any time, you can quickly revoke access by deleting the key.

Note to administrators

API keys need to be allowed through an authentication proxy in order to reach Connect. The Proxied Authentication section of the Posit Connect Admin Guide has more information about adding API key support to your proxy.

Note that RStudio handles authentication differently. For more information on connecting with the RStudio, see the Publishing from RStudio page.

To access content with an API key, you must provide an HTTP header whose key is Authorization and value is Key THE_API_KEY. The X-RSC-Authorization header is also accepted in a similar fashion.

All requests to content must be made to the target URL of the published content. You can find the target URL by clicking the Open Solo button in the upper-right of the Content View page. (Note: on narrow screens, the Open Solo button might be located in the … menu in the upper-right of the Content View.)

Open Solo button.

Creating and deleting an API key

To create an API key, click on the circular picture in the top-right portion of the screen. The picture might have your username next to it if you are viewing Posit Connect on a large screen.

User menu with Profile, API Keys, and Logout items.

Click Manage Your API Keys in the menu that appears. This takes you to the API Keys page.

API Keys page showing no API keys created.

On the API Keys page, click New API Key and follow the prompt to name your API key and select its role.

Dialog titled Create API Key with the name 'my_api_key' entered and the role 'Publisher' selected.

After creating an API key, you can view the key and are given an opportunity to put it in a safe location. Once you close the dialog, you will not be shown the API key again. This helps to keep your user account safe.

A created API key.

If you have lost an API key, or if you simply don’t need to use the API key anymore, remove the API key by clicking the trash bin icon on the far right column of the API key list.

API Key list showing 'my_api_key' and a trash bin icon.

When you click the trash bin icon, Connect prompts you to confirm that you want to delete the API key. Successfully deleting the API key shows a green status message at the top of the screen.

Using an API key

This section contains examples of how to use API keys to obtain or interact with content deployed to Posit Connect. These examples assume that your Posit Connect API key is available in the environment variable CONNECT_API_KEY.

export CONNECT_API_KEY=q9R4ylb3K3RPB7AB46il8mxjjcYsaClW

The examples in this section use the curl command-line utility to perform basic authenticated API key requests against content hosted by Posit Connect.

The Using API keys from code section shows how to make these same requests from Python and R. The Connect Server API Cookbook contains recipes which interact with the Connect Server API using API keys.

Static content

You can use API keys to download resources associated with static content (plots and previously rendered HTML).

Assume you have published a plot to Posit Connect and it has the URL: http://connect.company.com/content/24/target.html.

Download this content using your API key and the curl command-line program:

curl -O -H "Authorization: Key ${CONNECT_API_KEY}" \
    "http://connect.company.com/content/24/target.html"

The -O option tells curl to write a file named by the remote filename. In this case, it would write to the target.html file.

Write to a different filename (output.html in this example) using the -o option:

curl -o output.html -H "Authorization: Key ${CONNECT_API_KEY}" \
    "http://connect.company.com/content/24/target.html"

API content types

You can use API keys to make authenticated requests to API content such as Flask, Plumber, FastAPI, TensorFlow Models, and types that build off of those frameworks like Tableau Analytics Extensions and Vetiver.

Authenticated requests are required for API content set to either of the following sharing settings:

  • All users - login required
  • Specific users or groups

API content set to the “Anyone - no login required” setting (only available in select Connect licenses) does not require authenticated requests to access.

Plumber API example

Using the plumber API definition:

## plumber.R

#* @get /mean
normalMean <- function(samples=10){
  data <- rnorm(samples)
  mean(data)
}

The function normalMean is exposed through the /mean endpoint. It takes an optional samples query argument.

Assume this Plumber API is available on Posit Connect with the URL: http://connect.company.com/my-api/.

You can call this API using an API key and the curl command-line program:

curl -H "Authorization: Key ${CONNECT_API_KEY}" \
    "http://connect.company.com/my-api/mean?samples=5"

Using API keys from code

This section shows how to use API keys from your Python and R code.

All of these examples assume that your Posit Connect API key is available in the environment variable CONNECT_API_KEY and the base URL to your Posit Connect server is in the CONNECT_SERVER environment variable.

These environment variables need to be set up in your local environment.

export CONNECT_API_KEY=q9R4ylb3K3RPB7AB46il8mxjjcYsaClW
export CONNECT_SERVER=https://connect.company.com/

Python with posit-sdk

The posit-sdk package wraps the APIs of Posit’s professional products in a Pythonic interface. Many features of the Connect Server API, such as content and users, are exposed through classes and methods in the package, but you can also use it to make arbitrary requests of any endpoint on Connect.

If CONNECT_SERVER and CONNECT_API_KEY are specified in environment variables, you don’t need to pass them to the Client constructor.

# -*- coding: utf-8 -*-
from posit import connect

client = connect.Client()

result = client.get("/content/24/mean", params = { "samples": 5 }).json()

The result object is defined by parsing the JSON response data. It contains the result computed by normalMean in our Plumber API.

R with connectapi

The connectapi package makes it easy to work with the Connect Server API from R. Like the Python SDK, there are many convenience functions defined, but you can also make requests of any endpoint.

Here as well, when CONNECT_SERVER and CONNECT_API_KEY are specified in environment variables, they are picked up automatically by connect().

library(connectapi)

connectServer <- Sys.getenv("CONNECT_SERVER")
connectAPIKey <- Sys.getenv("CONNECT_API_KEY")

resp <- httr::GET(connectServer,
    path = "/content/24/mean",
    query = list(samples = 5),
    add_headers(Authorization = paste0("Key ", connectAPIKey)))
result <- httr::content(resp, as = "parsed")

The result object is defined by parsing the JSON response data. It contains the result computed by normalMean in our Plumber API.