API Keys

Posit Connect allows users to access hosted content outside the web browser by utilizing API keys - e.g. via shell scripts. API keys are enabled by default. To change this behavior please see the Configuring API Keys section.

How this works

API keys are associated with user accounts. 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 the user’s own role.

If a user has a compromised API key, the key should be deleted as soon as possible. The administrator may wish to lock the account if the user is having difficulty deleting the API key.

To retrieve static content or to invoke the endpoints of API content types via API keys, an HTTP request must be made to the target URL of the published content. For content requiring authenticated access, the request must contain an HTTP header whose key is Authorization and value is set to Key CONNECT_API_KEY.

Authorization: Key ABCDEFGHIJKLMNO

Note

Use the information above to allow API keys to pass through a Proxy.

API keys have the same authorization access levels as the user that owns them. Someone who uses an API key will be able to view all content that the owner of the API key has access to. API keys are shared secrets and as such they should be stored securely and only be given to trusted applications. It is advisable that content requests be made securely over HTTPS. If a user believes that an API key has been compromised, they can revoke just that key by deleting it.

Users may create API keys with a more restrictive role than they have been assigned by designating the key 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 API; that same key cannot publish content even though it belongs to a publisher user.

The Accessing Content via API Keys section of the Connect User Guide explains how to create and use API keys.

To learn how to configure Connect to listen for HTTPS requests, please see the HTTPS configuration appendix.

Configuration

Disabling API key authentication

Disable Authentication.APIKeyAuth to disallow API keys. This choice also disables Applications.DefaultAPIKeyEnv.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Authentication]
APIKeyAuth = false

Automatic API keys

The CONNECT_API_KEY environment variable is automatically provided to running content. This variable contains an ephemeral API key that exists for the duration of the underlying process.

Content owners can overwrite CONNECT_API_KEY with a custom environment variables.

The automatic addition of CONNECT_API_KEY can be disabled with the Applications.DefaultAPIKeyEnv option.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Applications]
DefaultAPIKeyEnv = false