Entitlements

Entitlement tokens are read-only tokens that your users (or customers) can use for downloading files - or more precisely, for getting read-only access to repository contents. You can use them to distribute files to users who don't have logins to Cloudsmith, or for "licensing" software by associating an entitlement token per customer.

If you'd like to track downloads for specific customers, the best practice is to create an entitlement token per customer, then use that token when you're providing download links for them. It also means you can revoke their token if they've lapsed their subscription with you, or change it for other reasons.

We also offer a "basic auth" method of authenticating with the website, which means it uses your username/password to authenticate instead of embedding a token into the URL. You could use this to create a separate "bot" user whose sole purpose is to authenticate for downloads via server installations.

For Vendors

If you're selling software and distributing it via Cloudsmith, you'll likely have a license that is associated per Customer and which dictates their terms of usage. Associating the license with an entitlement allows you to control and track downloads of the software specifically for that license. For example, you could only allow the Customer to download specific packages, between August 1st 2024 and August 1st 2024, up to a maximum of 10 downloads from one location (i.e. a single client). Each entitlement can have different restrictions, and you can use the freeform (JSON-based) metadata to add your own information into the entitlement.

📘

Entitlement tokens are only available on private repositories, as by definition, public repositories are open and provide read-only access to anyone.

Entitlement Tokens also cannot be used to authenticate to the Cloudsmith API. Entitlement Tokens are used to authenticate for package downloads only.

Standard Entitlement Tokens

You can create Standard Entitlement Tokens via the Website UI, via the Cloudsmith CLI or via the Cloudsmith API

User Entitlement Tokens

User Entitlement Tokens are very similar to Standard Entitlement Tokens. They are created automatically when a user with permissions views a repository. They are associated with the user and the user's permissions.

Only the user themselves and administrators of the repository can see the user-based tokens. If the user is removed from the repository, teams or the organisation, then the token will no longer work for authentication.

Multi-Repository Tokens

We don't support creating entitlement tokens that are valid across multiple repositories (although this functionality is under consideration for our roadmap). However, there are two ways you can achieve something similar:

• You can sync entitlement tokens across multiple repositories.
• You can create a token in several repositories with a custom token string, thereby giving you a token where the string will be valid in more than one repository.

Permissions

How can I define a user with minimum rights to only create entitlements on a certain repository?
The permissions aren't granular enough to allow for entitlement token creation only (which requires at least "Write" access). However, a user (or a user in a team) with "Write" access can only modify (move/delete/etc) their own packages. So if you create a user/team for updating entitlement tokens, although they will have write access to the repository, to create tokens, they will not be able to modify the existing packages that are there.
In other words, separate the "uploader" account (this could also just be your normal staff) from the account that will create entitlement tokens.

Counting Token Usage

Some Cloudsmith pricing plans include a specific number of entitlement tokens. Only active tokens count towards this limit; disabled and deleted tokens are not counted.