The Cloudsmith Developer Hub

Welcome to the Cloudsmith Developer Hub. You'll find comprehensive guides and documentation to help you start working with Cloudsmith as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Entitlements

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.

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 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.


Multi-Repository Tokens

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.

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.

Updated 2 months ago


What's Next

You can manage Entitlement Tokens via the Website UI, the Cloudsmith CLI or the Cloudsmith API.

Managing Entitlement Tokens via the Cloudsmith CLI
Managing Entitlement Tokens via the Cloudsmith API
Managing Entitlement Tokens via the Website UI

Entitlements


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.