Authentication

The majority of 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 don't need authentication (although they may provided 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/1.0 401 Unauthorized
Server: Werkzeug/0.11.11 Python/2.7.12
Date: Sun, 29 Jan 2017 18:40:49 GMT

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

API Key / User Token Authentication

Instead of providing your email and password, it is recommended that you instead authenticate to the API by specifying your API Key.

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 token 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/1.0 401 Unauthorized
Server: Werkzeug/0.11.11 Python/2.7.12
Date: Sun, 29 Jan 2017 18:38:24 GMT

{
  "detail":"Invalid token."
}

📘

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.

🚧

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 our suggestion is to create a lesser privileged bot-user account and use that instead for scripts/automation.