Token Authentication

Package Manager supports token-based authentication for both API access and authenticated repositories. This method uses API tokens to control access to Package Manager features and repositories.

Configuring Authenticated Repositories

EnhancedAdvanced

This section provides step-by-step instructions for creating and configuring authenticated repositories using API tokens.

To set up an authenticated repository, follow these steps:

  1. Create the authenticated repository

    You can create a new repository that requires authentication by running rspm create repo with the --authenticated flag:

    Terminal
    # Create an authenticated CRAN repository:
rspm create repo --name=cran --description='Access CRAN packages' --authenticated
rspm subscribe --repo=cran --source=cran

# Create an authenticated PyPI repository:
rspm create repo --name=pypi --type=python --description='Access PyPI packages' --authenticated
rspm subscribe --repo=pypi --source=pypi

# Create an authenticated Bioconductor repository:
rspm create repo --type=bioconductor --name=bioconductor --description='Access Bioconductor packages' --authenticated

    Or edit an existing repository to require authentication:

    Terminal
    rspm edit repo --name=cran --authenticated

    To require authentication by default for new repositories, configure the Authentication.NewReposAuthByDefault setting.

  2. Create an API token that includes the repos:read scope.

    Terminal
    rspm create token --scope=repos:read --repos='*' --description="Allows read access for all repos" --user="repo-reader"

  3. Configure client access

    Instruct users to configure R or configure Python to use the API token.

    If you are using Connect or Workbench with authenticated repositories, you can also configure credentials globally for all users. See Configuring Posit Connect and Configuring Posit Workbench.

API Tokens

API tokens are used to:

  • Advanced Authenticate with the server when using the Package Manager CLI remotely.
  • EnhancedAdvanced Authenticate users for repositories that require authentication.

API Token Security

For the best security, please consider the following when creating API tokens:

  • Grant access only to the minimum necessary scope to run the required commands. For sources tokens, grant access only to the required sources using the --sources flag.
  • Provide a token expiration with the --expires flag when creating a token. Tokens never expire by default.
  • Rotate tokens regularly.

Creating API Tokens

You can create a token using the rspm create token command. API tokens have several properties. The token scope, description, expiry, and sources can only be set when the token is created; they cannot be changed. Tokens can be revoked at any time.

Property Description
Scope The type of access granted by the token, such as sources:write or global:admin. See API Token Scopes for a list of available scopes. Required.
Description A description of the token; provided when token is created. Required.
User The username or email associated with the token; provided when token is created. Required.
Sources The sources to which the token is granted access. When set to *, the token is valid for all current and future sources. Required for sources tokens.
Repos The repos to which the token is granted access. When set to *, the token is valid for all current and future repos. Required for repos tokens.
Expires An expiration time for the token. The token cannot be used after this time. An expiry of never means that the token never expires. You can specify a duration like 30d (30 days) or 5m (5 minutes). Defaults to never.
Revoked A revoked token cannot be used; revoked tokens cannot be reinstated.
Note

When an API token is created for a specific local or git source, the token is valid only for the source you specified. If you delete the source and recreate a new source with the same name, you will need to create a new API token for the new source.

Examples

  • Create a repos:read token with access to download packages from all repos (no expiry):

    Terminal
    rspm create token --scope=repos:read --repos='*' \
  --description="Allows read access for all repos" --user="repo-reader"

  • Create a sources:write token with access to upload packages to all sources (no expiry):

    Terminal
    rspm create token --scope=sources:write --sources='*' \
  --description="Allows write access for all sources" --user="source-publisher"

  • Create a sources:write token with access to upload packages to the internal and internal-git sources (no expiry):

    Terminal
    rspm create token --scope=sources:write --sources=internal,internal-git \
  --description="Allows write access for the internal and internal-git sources" --user="internal-publisher"

  • Create a metadata:admin token with access to manage custom metadata (30 day expiry):

    Terminal
    rspm create token --scope=metadata:admin --expires=30d \
  --description="Allows full access to manage metadata" --user="metadata-manager"

  • Create a global:admin token with full administrative access (30 day expiry):

    Terminal
    rspm create token --scope=global:admin --expires=30d \
  --description="Allows global admin access" --user="admin@example.com"

See the rspm create token documentation for more examples.

API Token Scopes

Name Tiers Description
global:admin

Advanced

 Grants full access to manage the Package Manager server.
sources:write

Advanced

 Grants read and write access to sources, such as uploading packages, removing packages, creating Git builders, and importing Git credentials. Access can be limited to specific sources or granted to all sources with --sources='*'.
repos:read EnhancedAdvanced Grants read access to authenticated repositories. Access can be limited to specific repositories or can be granted to all repositories with --repos='*'.
blocklist:admin

Advanced

 Grants full access to manage the blocklist.
blocklist:read

Advanced

 Grants read access to the blocklist.
metadata:admin

Advanced

 Grants full access to manage metadata.
metadata:read

Advanced

 Deprecated. Grants read access to metadata. Existing tokens can be used, but you cannot create new tokens with the metadata:read scope. New tokens should use the repos:read scope.

Listing API Tokens

You can list API tokens with the rspm list tokens command. Use the --expired and --revoked flags to filter the results.

Revoking API Tokens

You can revoke API tokens at any time with the rspm revoke token command. Revoked tokens cannot be reinstated, and are no longer valid for use. To revoke a token, you can provide the token or the GUID associated with the token. You can List API Tokens to find the GUID associated with each token.

Back to top