Entitlement tokens are read-only tokens that you use for downloading files, or rather, 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, etc.
If you'd like to track downloads for specific customers then 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, etc.
We do 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 who's sole purpose is to authenticate for downloads via server installations.
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 2018 and August 1st 2019, 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.
User Entitlement Tokens are very similar 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.
Currently, we don't support creating entitlement tokens that are valid across multiple repositories (This functionality is on our roadmap though). However, there are two ways you can achieve this:
- 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.
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.
Updated about 1 year ago
You can manage Entitlement Tokens via the Website UI, the Cloudsmith CLI or the Cloudsmith API.