Skip to content

Latest commit

 

History

History
126 lines (85 loc) · 7.64 KB

api-key-scopes.md

File metadata and controls

126 lines (85 loc) · 7.64 KB
Raw
layout title previous next
default
API key scopes
/rubygems-org-rate-limits
/run-your-own-gem-server

RubyGems.org API keys, their scopes, and CLI usage

You can create multiple API keys based on your requirements. API keys have varying scopes that grant specific privileges. Using API keys with the least amount of privilege makes your RubyGems.org account more secure by limiting the impact a compromised key may have.

Create a new API key

Visit your RubyGems.org account settings page and click on API KEYS. You will be prompted for your account password to confirm your identity.

Settings API key{:class="t-img"}

If you have never visited this page before, you should see at least one key with the name legacy-key. The legacy-key is relic of the time when RubyGems.org used to have a single API key per account with full access. We recommend that you migrate away from legacy-key as soon as possible.

Click on New API Key to create a new API key for your account.

Settings API key{:class="t-img"}

Enter a name to help you identify the environment the API key may be used in (eg: ci-push-key, mirror-webhook-key, etc.). Check all the scopes you may want to enable and click on create.

Note: Show dashboard is an exclusive scope, and it can't be enabled in combination with any other scope.

New API key{:class="t-img"}

On the following page, you should see the new API key.

API key created{:class="t-img"}

The Age column shows how old is the key. The Last access column shows the last time (in UTC) the key was used in a successful authentication. You can use the Edit button to update the scopes of the key. You can use the Reset button in the last row to delete all the API keys associated with your account.

Usage with gem CLI

An API key created as outlined above can be used in the gem CLI directly by setting it in an environment variable called GEM_HOST_API_KEY, e.g.

$ GEM_HOST_API_KEY=rubygems_123456 gem push example-1.2.3.gem

This approach is suitable for non-interactive situations, e.g. for CI/CD-based gem publishing processes. On a personal development machine that you can directly access, the interactive sign-in using gem signin (see below) is usually preferrable.

Creating from gem CLI

Note: You need rubygems 3.2.0 or newer if you like to create API keys with scopes from the gem CLI.

Running gem signin will prompt you for your RubyGems.org credentials, key name, and scopes to enable for the key. The default choice for all scopes is not to enable them.

$ gem signin
Enter your RubyGems.org credentials.
Don't have an account yet? Create one at https://rubygems.org/sign_up
   Email:   [email protected]
Password:

API Key name [4458ffe32b0c-unknown-user-20201231104303]:   docker-push-key
Please select scopes you want to enable for the API key (y/n)
index_rubygems [y/N]:
push_rubygem [y/N]:   Y
yank_rubygem [y/N]:
add_owner [y/N]:
remove_owner [y/N]:
access_webhooks [y/N]:
show_dashboard [y/N]:

Signed in with API key: docker-push-key.

An API key will automatically be created (default key name: hostname-whoami-timestamp) with the required scope when we couldn't find any API key on your host. Similarly, the scope of the existing API key on the host will be updated with the required scope if the key didn't have the correct scope.

$ gem yank begone -v 4.1.48
Yanking gem from https://rubygems.org...
The existing key doesn't have access of yank_rubygem on https://rubygems.org. Please sign in to update access.
   Email:   [email protected]
Password:
Added yank_rubygem scope to the existing API key
Successfully deleted gem: begone (4.1.48)

API key scopes

  • Index rubygems: List all RubyGems of your account
  • Push rubygems: Create a new RubyGem or publish a new version of any RubyGem you own
  • Yank rubygems: Remove a published version of any RubyGem you own
  • Add owner: Add a user to owners of any RubyGem you own
  • Remove owner: Remove a user from owners of any RubyGem you own
  • Access webhooks: List, create, delete or fire webhooks associated with your account
  • Show dashboard: Access to atom feed of your RubyGems.org dashboard. It is an exclusive scope and can't be enabled with any other scope.

Scope an API key to a gem

Enabling one or more of the key scopes related to creating or updating a gem (Push rubygems, Yank rubygems, Add owner, and Remove owner) will allow you to scope one of your gems to the API key. The operations corresponding to these scopes will only be valid on the selected gem.

New API key with gem scope{:class="t-img"}

If you are using a key to modify only one of your gems, please consider gem scoping your keys.

Note: When your ownership to a gem is removed, API keys scoped to that gem will become invalid and cannot be used.

Enable MFA on specific API keys

If your account has MFA enabled on the UI and gem signin authentication level, you have the option to enable MFA on a specific API key. This will require an OTP code for gem push, yank, owner --add/--remove commands.

You can toggle this option when creating or editing an API key on the UI. New API key with MFA enabled{:class="t-img"}

Migration from legacy-api key

The legacy API key of your account has been migrated to one with all scopes enabled. We strongly recommend that you delete this key and replace it with a new API key with minimum scopes enabled.

  • Visit API keys page of your account and click on delete button for the key named legacy-key.
  • Run gem signout on all hosts where you have used the legacy API key
  • Make sure you have rubygems 3.2.0 or newer installed. Run gem update --system to update your rubygem to the latest release.
  • Run gem signin to create a new API key.

If it is not possible for you to update your rubygems, you can still use the new API key by creating a new key using the web UI and replacing the key in ~/.gem/credentials or ~/.local/share/gem/credentials file.

$ cat ~/.local/share/gem/credentials
:rubygems_api_key: rubygems_cec9db9373ea171daaaa0bf2337edce187f09558cb19c1b2

Note: The legacy endpoint to fetch API keys, GET /api/v1/keys has been updated to create a new API key on each request. As a security precaution, the new API keys are stored in our database after one-way encryption. It is no longer possible for us to fetch the same API key in plain text.