Most resources provided by the API require some form of authentication, which identifies the client to the API in the context of a particular user. Other resources are accessible anonymously, so they don't need authentication (although they may provide expanded detail for authenticated users). You can use the following methods to authenticate:
Basic Authentication
The simplest (but least recommended) way to authenticate is to provide your login email and password when making API requests (replacing <email> with your username and <password> with your password):
curl -u "<email>:<password>" https://api.cloudsmith.io/user/self/
Specifying an invalid email and/or password will result in an 401 Unauthorized status code, and the body will specify that invalid credentials were received. Let's see it in action:
curl -i -u "example:wrongpassword" -X OPTIONS https://api.cloudsmith.io/user/self/
HTTP/2 401
date: Thu, 09 Mar 2023 16:52:55 GMT
server: Cloudsmith MCP
{"detail": "Invalid username/password."}
Security Warning - Access All Areas
We probably shouldn't need to say this but disclosure of your email and password will allow a malicious third-party to takeover your account and cause damage. We recommend using an API Key instead and using a lesser privileged account for API access - see Keep Your Secrets Close below for suggestions.
Instead of providing your email and password, it is recommended that you instead authenticate to the API by specifying your API Key.
API Key Authentication
Getting your API Key
You can find your API Key within your User Settings or you can request (or reset) it via the Users Token API Endpoint.
Cloudsmith Entitlement Tokens cannot be used to authenticate to the Cloudsmith API. Entitlement Tokens are used to authenticate for package downloads only.
You can specify your API Key via the X-Api-Key header when making requests (replacing <key> with your actual API Key):
curl -H "X-Api-Key: <key>" https://api.cloudsmith.io/user/self/
You can also specify your API Key via the Authorization header when making requests (replacing <key> with your actual API Key):
curl -H "Authorization: token <key>" https://api.cloudsmith.io/user/self/
Specifying an invalid API Key will result in an 401 Unauthorized status code, and the body will specify that an invalid token was received. Let's see it in action:
curl -i -H "X-Api-Key: foobar" -X OPTIONS https://api.cloudsmith.io/user/self/
HTTP/2 401
date: Thu, 09 Mar 2023 16:55:35 GMT
server: Cloudsmith MCP
{"detail": "Invalid token."}
Security Warning - Keep Your Secrets Close
If your API key is given to someone else they will be able to access the API in its entirety as you (although they won't be able to login to the website itself, which makes this method slightly more secure that using Basic Authentication). This should be viewed as a security risk and every effort should be taken to protect your API Key from disclosure. If you need to add read-only access, we suggest creating a lesser privileged [service account](https://help.cloudsmith.io/docs/service-accounts} and using that instead for scripts/automation.
