Authentication and permissions

All of the functionality described in this page applies to paid subscriptions (and free trials) only. The free version of RepoForge.io is for public/open source projects only. If you are using the free version of RepoForge.io, all of your packages will be public, and you won't be able to make a package private, or change the permissions of a package.

Introduction

RepoForge.io implements a flexible authentication and permissions system to let you control exactly who can push data to, or pull data from, your RepoForge.io account. This article goes into detail on each of the available Authentication methods.

Access tokens vs user credentials

Whenever you login to your RepoForge.io dashboard, you do so using your user credentials. You can also use these same credentials to interact with the package APIs (e.g to push packages to and pull packages from the Python, Docker, Debian, Conda and Maven registry APIs). While user credentials work fine when you're just starting out with RepoForge.io, we'd strongly recommend using Access Tokens for any more serious work, e.g. building a devops pipeline. Using access tokens instead of user credentials is more secure and place a marginally lighter load on the RepoForge.io servers. What's more, you can create as many access tokens as you like, whereas creating additional user accounts means ugrading your subscription.

You can create access tokens at any point from the Access Tokens page of the RepoForge.io dashboard:

Just click on Create new access token, give your token a name, and move the roles you want it to assume from Available roles to Selected roles:

Keep in mind that you will only be shown the token once, so you'll need to store it somewhere secure. From the Access Tokens page you can also edit a token's name and roles (pencil icon), rotate its value (circular arrows icon) or delete it (trash icon) at any time.

You can then use it in place of your password when interacting with your Python API. The username can be any value - by convention we use __token__:

pip install twine
twine upload --repository-url https://api.repoforge.io/my-hash-id/ my-package.whl
Enter your username: __token__
Enter your password: {my-api-key}

About roles

Users and Access Tokens in RepoForge.io can assume one or more roles. Your credentials or Access Tokens will not be able to interact with RepoForge.io's APIs unless they have assumed the correct role for the given API. For example, to push a new Python package to RepoForge.io, you must do so using credentials or an Access Token that assumes the Python - Full access role.

You can see every role in your account on the roles page of the dashboard:

Here is the list of standard roles available to RepoForge.io:

• Dashboard access: This role is assumed by all RepoForge.io users and lets you log into the dashboard. It is selected for you when you create a user, and you cannot remove it. Access Tokens may not assume this role (you must be a user to login).
• API access: This role lets you interact with the RepoForge.io REST API. It can only be assumed by an Access Token, not a user account.
• Python - Full access / Python - Read only: Allows read write or read only access to interact with the Python APIs (e.g it lets you use uv/twine/pip)
• Docker - Full access / Docker - Read only: Similar to the above, but for Docker registries
• NPM - Full access / NPM - Read only: Similar to the above, but for NPM projects. Keep in mind that due to the way npm handles authentication, it can only be assumed by an Access Token.
• Debian - Full access / Debian - Read only: Similar to the above, but for Debian packages
• Conda - Full access / Conda - Read only: Similar to the above, but for Conda channels
• Maven - Full access / Maven - Read only: Similar to the above, but for Maven artifacts, published and resolved with Maven or Gradle

Beyond the limitations described above, you can attach as many roles as you like to any Access Token or user account. When you first create your RepoForge.io account, you will automatically be assigned the Dashboard access role plus the Full access role for each package type (Python, Docker, NPM, Debian, Conda and Maven). The API access role is not assigned to anyone by default - create an access token that assumes it to use the REST API.

Limiting access to individual packages

Whenever you push a new Python package to RepoForge.io, it will be created with default permissions. This means that any user or access token with the Python - Read only role can install that package.

However, it is possible to change the package permissions mode to use “package-level” permissions instead. This applies to all supported package types. To do this, click the pencil icon next to the package's Permissions mode in the dashboard and confirm that you want to switch to PACKAGE_LEVEL:

When in this mode, the generic Python roles are no longer sufficient to access the package. When you switch a package to package level permissions, it will create two new roles - (package name) full access and (package name) read access. In order to continue to read/write the package, you must first edit your users or access tokens to assume these newly created roles. You can switch the package back to DEFAULT mode in the same place.

Making packages public

By default, all new packages will be marked as private, meaning that it is not possible to pull/download them with an unauthenticated request. You can make a package public by switching off the Private toggle for the package in the dashboard, and confirming in the dialog that appears:

When a package is public, anybody with the URL will be able to pull the package without auth.

Marking a package as public doesn’t have any impact on write permissions. You cannot push new versions or new packages without authentication.

All supported package types can be made public in this way.

Python authentication

Write access - using twine

There are three ways to authenticate when pushing packages to RepoForge.io using twine:

1. Using --stdin

twine upload --repository-url https://api.repoforge.io/my-hash-id/ my-package.whl
Enter your username: __token__
Enter your password: your-access-token

2. Using the -u and -p arguments

twine upload --repository-url https://api.repoforge.io/my-hash-id/ -u __token__ -p your-access-token my-package.whl

3. Using environmental variables

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=your-access-token
twine upload --repository-url https://api.repoforge.io/my-hash-id/ my-package.whl

Using uv

Refer to using uv for how to authenticate while publishing and installing with uv.

Using poetry

Refer to using poetry to see best practices on authenticating while using Poetry and RepoForge.io.

Read access - using pip

pip also provides a few auth options:

1. Using --stdin

pip install -i https://api.repoforge.io/my-hash-id/ mypackage
User for api.repoforge.io: __token__
Password: *******

2. Using basic auth

pip install -i https://__token__:your-access-token@api.repoforge.io/my-hash-id/ mypackage

Docker authentication

Use the below command to log in to your docker registry:

docker login docker.repoforge.io/my-hash-id/my-registry-name -u __token__

Once logged in, you should be able to both push and pull images with the below commands. Please note that even if you are able to login successfully, your requests to docker push/docker pull may still fail depending on your permissions - the credentials you used to login must have assumed the correct roles for your registry.

NPM authentication

Due to the way npm works, it is NOT possible to access your NPM registry using user credentials - only access tokens will work

To use an access token to authenticate requests to your private NPM repository, use the following command:

npm config set //api.repoforge.io/npm/my-hash-id/:_authToken {VALID_NPM_AUTH_TOKEN}

Debian and Conda authentication

Debian and Conda use the same credentials as the other package types: either user credentials or an access token (passed as the password, with __token__ as the username) that assumes the relevant Debian or Conda role. See Working with Debian and Working with Conda for examples.

Maven and Gradle authentication

Maven and Gradle send HTTP basic auth: use an access token that assumes a Maven role as the password, with any username. Maven reads them from a <server> entry in settings.xml, and Gradle from a repository's credentials block. See Using Maven and Gradle for examples.

Two-factor authentication

You can add a second factor to your dashboard login with an authenticator app. See Two-factor authentication.