Generating API Keys

API keys provide a way to programmatically authenticate against the Cycle platform. Learn how to create them and manage their permissions.

Cycle authentication is an OAuth 2 based system that supports multiple ways to verify your credentials. The general flow goes like this:

  1. User passes credentials (username & password, API key, etc) to a Cycle authentication server
  2. Authentication server does a check on the credentials and issues a JSON Web Token (JWT)
  3. The JWT is passed as a header in each request to the API

After two hours, the authentication token expires. However, each authentication token comes with a paired refresh token, good for one session refresh. Refresh tokens expire one hour after the authentication token, giving you a short window to reauth. If your refresh token expires, you will need to generate a new token using your credentials.

Though it's a bit unorthodox, this means you never use your API Key directly in your requests to the API. It just substitutes as a username/password combination. We decided to go this route to provide an extra layer of security, where you are never sending your API key over the network, instead substituting it for temporary tokens. This doesn't imply sending JWTs over an unsecure is safe, but instead minimizes the amount of time a hacker would be able to take advantage of a stolen token. Treat your API key as sacred as your password!

Generating A New Key

Go to project settings, and click the "API Keys" tab at the top. If you don't have an API key, you'll be presented with a button to create one.

It cannot be overstated how important it is to use proper techniques to keep your API key secure, even from general people within your organization. Don't ever paste it into source-controlled code, or share it on an unsecure channel.
  1. In the name field, enter a unique name associated with what this key will be used for.
  2. Restrict access to particular IPs for an extra layer of security. If you want this key to be usable by any IP, leave this field blank.
  3. Check any permissions you want to apply to this key. Be careful to only give the exact permissions your app needs. See this list for a complete breakdown of permissions.
  4. Hit "Create API Key" once you're sure your key is configured correctly. You'll be taken back to the API Keys list, where you can copy your key.

Deleting A Key

From the API key table under project settings, you will find a red delete button next to each key. Click it to remove it from your project.

Need Help?

If you've got questions about the platform or need some help getting started, our team is more than happy to assist. Whether you're new to containers or just new to Cycle, reach out to us via livechat by clicking the blue circle in the bottom right corner. Join our Slack channel, and get help from the dev team or other members of the community.