API key scopes - RubyGems Guides

<!DOCTYPE html> <html lang="en-us"> <head> <title>API key scopes - RubyGems Guides</title> <meta charset="utf-8" /> <link rel="icon" href="/favicon.ico" type="image/x-icon"> <link rel="icon" href="/favicon.icns"> <meta http-equiv="Description" name="Description" content="Tutorials, guides, FAQs for RubyGems package management" /> <meta http-equiv="Keywords" name="Keywords" content="rubygems, gems, programming, ruby, packages" /> <meta content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0" name="viewport"> <link href="/stylesheets/application.css" rel="stylesheet" type="text/css" /> <script src="//code.jquery.com/jquery-3.6.0.min.js"></script> <script src="/javascripts/mobile-nav.js" type="text/javascript"></script> <script src="//use.typekit.net/omu5dik.js" type="text/javascript"></script> <script> try{Typekit.load();}catch(e){} </script> <script> $(function() { var path = window.location.pathname; $('a.nav--v__link[href="'+path.substring(0, path.length -1)+'"]').addClass('is-active'); var header_link = $('a.header__nav-link[href="'+path.substring(0, path.length -1)+'"]'); if(header_link.length > 0) { $('.header__nav-links a').removeClass('is-active'); header_link.addClass('is-active'); } }); </script>  <meta name="viewport" content="width=device-width"> <script type="text/javascript"> window.scrollTo(0, 1); </script>   </head> <body class="default"> <header class="header header--interior"> <div class="l-wrap--header"> <a class="header__logo-wrap" href="https://rubygems.org/"> <span class="header__logo" data-icon="⬡">⬢</span> <span class="t-hidden">RubyGems</span> </a> <a class="header__club-sandwich" href="#"> <span class="t-hidden">Navigation menu</span> </a> <div class="header__nav-links-wrap"> <form accept-charset="UTF-8" action="https://rubygems.org/search" class="header__search-wrap" id="main-search" method="get"> <input class="header__search" id="query" name="query" placeholder="Search Gems…" type="search" /> <label for="query"> <span class="t-hidden">Search gems</span> </label> <input class="header__search__icon" id="search_submit" type="submit" value="⌕" /> </form> <nav class="header__nav-links"> <a class="header__nav-link" href="https://rubygems.org/releases">Releases</a> <a class="header__nav-link" href="https://blog.rubygems.org">Blog</a> <a class="header__nav-link" href="https://rubygems.org/gems">Gems</a> <a class="header__nav-link is-active" href="/">Guides</a> <a class="header__nav-link" href="/contributing">Contribute</a> </nav> </div> </div> </header> <main class="main--interior"> <div class="l-wrap--b"> <a class="t-display page__heading" href="/">Guides</a> <div class="l-overflow"> <div class="l-col--l"> <ul class="nav--v"> <li><a class="nav--v__link" href="/rubygems-basics">RubyGems Basics</a></li> <li><a class="nav--v__link" href="/what-is-a-gem">What is a gem?</a></li> <li><a class="nav--v__link" href="/make-your-own-gem">Make your own gem</a></li> <li><a class="nav--v__link" href="/gems-with-extensions">Gems with Extensions</a></li> <li><a class="nav--v__link" href="/name-your-gem">Name your gem</a></li> <li><a class="nav--v__link" href="/publishing">Publishing your gem</a></li> <li><a class="nav--v__link" href="/security">Security Practices</a></li> <li><a class="nav--v__link" href="/managing-owners-using-ui">Managing owners using UI</a></li> <li><a class="nav--v__link" href="/removing-a-published-gem">Removing a Published gem</a></li> <li><a class="nav--v__link" href="/ssl-certificate-update">SSL Certificate Update</a></li> <li><a class="nav--v__link" href="/patterns">Patterns</a></li> <li><a class="nav--v__link" href="/specification-reference">Specification Reference</a></li> <li><a class="nav--v__link" href="/command-reference">Command Reference</a></li> <li><a class="nav--v__link" href="/rubygems-org-api">RubyGems.org API</a></li> <li><a class="nav--v__link" href="/rubygems-org-api-v2">RubyGems.org API V2.0</a></li> <li><a class="nav--v__link" href="/rubygems-org-compact-index-api">RubyGems.org Compact Index API</a></li> <li><a class="nav--v__link" href="/rubygems-org-rate-limits">RubyGems.org rate limits</a></li> <li><a class="nav--v__link" href="/api-key-scopes">API key scopes</a></li> <li><a class="nav--v__link" href="/run-your-own-gem-server">Run your own gem server</a></li> <li><a class="nav--v__link" href="/setting-up-multifactor-authentication">Setting up multi-factor authentication</a></li> <ul class="nav--v"> <li><a class="nav--v__link" href="/setting-up-webauthn-mfa">Setting up WebAuthn MFA</a></li> <li><a class="nav--v__link" href="/setting-up-otp-mfa">Setting up OTP MFA</a></li> </ul> <li><a class="nav--v__link" href="/using-mfa-in-command-line">Using multi-factor authentication in command line</a></li> <ul class="nav--v"> <li><a class="nav--v__link" href="/using-webauthn-mfa-in-command-line">Using WebAuthn for MFA</a></li> <li><a class="nav--v__link" href="/using-otp-mfa-in-command-line">Using OTP for MFA</a></li> </ul> <li><a class="nav--v__link" href="/mfa-requirement-opt-in">MFA requirement opt in</a></li> <li><a class="nav--v__link" href="/using-s3-source">Using S3 as gem source</a></li> <li><a class="nav--v__link" href="/resources">Resources</a></li> <li><a class="nav--v__link" href="/contributing">Contributing to RubyGems</a></li> <li><a class="nav--v__link" href="/faqs">Frequently Asked Questions</a></li> <li><a class="nav--v__link" href="/plugins">Plugins</a></li> <li><a class="nav--v__link" href="/cve">Common Vulnerabilities and Exposures</a></li> <li><a class="nav--v__link" href="/releasing-rubygems">Releasing RubyGems</a></li> <li><a class="nav--v__link" href="/trusted-publishing">Trusted Publishing</a></li> <ul class="nav--v"> <li><a class="nav--v__link" href="/trusted-publishing/adding-a-publisher">Adding to an existing gem</a></li> <li><a class="nav--v__link" href="/trusted-publishing/pushing-a-new-gem">Pushing a new gem</a></li> <li><a class="nav--v__link" href="/trusted-publishing/releasing-gems">Releasing gems</a></li> </ul> <li><a class="nav--v__link" href="/credits">Credits</a></li> </ul> </div> <div class="l-colspan--r"> <div class="t-body"> <p><em class="t-gray">RubyGems.org API keys, their scopes, and CLI usage</em></p> <p>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.</p> <h2 id="create-a-new-api-key">Create a new API key</h2> <p>Visit your RubyGems.org account <a href="https://rubygems.org/settings/edit">settings page</a> and click on <strong>API KEYS</strong>. You will be prompted for your account password to confirm your identity.</p> <p><img src="/images/settings-api-key.png" alt="Settings API key" class="t-img" /></p> <p>If you have never visited this page before, you should see at least one key with the name <em>legacy-key</em>. The <em>legacy-key</em> is relic of the time when RubyGems.org used to have a single API key per account with full access. We recommend that you <a href="#migration-from-legacy-api-key">migrate away from <em>legacy-key</em></a> as soon as possible.</p> <p>Click on <strong>New API Key</strong> to create a new API key for your account.</p> <p><img src="/images/api-keys-index.png" alt="Settings API key" class="t-img" /></p> <p>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.</p> <p><strong>Note:</strong> <em>Show dashboard</em> is an exclusive scope, and it can’t be enabled in combination with any other scope.</p> <p><img src="/images/new-api-key.png" alt="New API key" class="t-img" /></p> <p>On the following page, you should see the new API key.</p> <p><img src="/images/api-key-created.png" alt="API key created" class="t-img" /></p> <p>The <em>Age</em> column shows how old is the key. The <em>Last access</em> column shows the last time (in UTC) the key was used in a successful authentication. You can use the <strong>Edit</strong> button to update the scopes of the key. You can use the <strong>Reset</strong> button in the last row to delete <em>all</em> the API keys associated with your account.</p> <h2 id="usage-with-gem-cli">Usage with gem CLI</h2> <p>An API key created as outlined above can be used in the <code class="language-plaintext highlighter-rouge">gem</code> CLI directly by setting it in an environment variable called <code class="language-plaintext highlighter-rouge">GEM_HOST_API_KEY</code>, e.g.</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>$ GEM_HOST_API_KEY=rubygems_123456 gem push example-1.2.3.gem </code></pre></div></div> <p>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 <code class="language-plaintext highlighter-rouge">gem signin</code> (see below) is usually preferrable.</p> <h2 id="creating-from-gem-cli">Creating from gem CLI</h2> <p><strong>Note:</strong> You need rubygems 3.2.0 or newer if you like to create API keys with scopes from the gem CLI.</p> <p>Running <code class="language-plaintext highlighter-rouge">gem signin</code> 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.</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>$ gem signin Enter your RubyGems.org credentials. Don't have an account yet? Create one at https://rubygems.org/sign_up Email: john@doe.com 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. </code></pre></div></div> <p>An API key will automatically be created (default key name: <em>hostname-whoami-timestamp</em>) 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.</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>$ 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: john@doe.com Password: Added yank_rubygem scope to the existing API key Successfully deleted gem: begone (4.1.48) </code></pre></div></div> <h2 id="api-key-scopes">API key scopes</h2> <ul> <li><a href="https://guides.rubygems.org/rubygems-org-api/#get---apiv1gemsjsonyaml">Index rubygems</a>: List all RubyGems of your account</li> <li><a href="https://guides.rubygems.org/rubygems-org-api/#post---apiv1gems">Push rubygems</a>: Create a new RubyGem or publish a new version of any RubyGem you own</li> <li><a href="https://guides.rubygems.org/rubygems-org-api/#delete---apiv1gemsyank">Yank rubygems</a>: Remove a published version of any RubyGem you own</li> <li><a href="https://guides.rubygems.org/rubygems-org-api/#post---apiv1gemsgem-nameowners">Add owner</a>: Add a user to owners of any RubyGem you own</li> <li><a href="https://guides.rubygems.org/rubygems-org-api/#delete---apiv1gemsgem-nameowners">Remove owner</a>: Remove a user from owners of any RubyGem you own</li> <li><a href="https://guides.rubygems.org/rubygems-org-api/#webhook-methods">Access webhooks</a>: List, create, delete or fire webhooks associated with your account</li> <li><a href="https://rubygems.org/dashboard">Show dashboard</a>: Access to atom feed of your RubyGems.org dashboard. It is an exclusive scope and can’t be enabled with any other scope.</li> </ul> <h2 id="enable-mfa-on-specific-api-keys">Enable MFA on specific API keys</h2> <p>If your account has MFA enabled on the <strong>UI only</strong> or <strong>UI and gem signin</strong> <a href="https://guides.rubygems.org/setting-up-multifactor-authentication/#authentication-levels">authentication level</a>, you have the option to enable MFA on a specific API key. This will require an OTP code for <code class="language-plaintext highlighter-rouge">gem push</code>, <code class="language-plaintext highlighter-rouge">yank</code>, <code class="language-plaintext highlighter-rouge">owner --add/--remove</code> commands.</p> <p>You can toggle this option when creating or editing an API key on the UI. <img src="/images/new-mfa-api-key.png" alt="New API key with MFA enabled" class="t-img" /></p> <h2 id="migration-from-legacy-api-key">Migration from legacy-api key</h2> <p>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.</p> <ul> <li>Visit <a href="https://rubygems.org/profile/api_keys">API keys page</a> of your account and click on <strong>delete</strong> button for the key named <em>legacy-key</em>.</li> <li>Run <code class="language-plaintext highlighter-rouge">gem signout</code> on all hosts where you have used the legacy API key</li> <li>Make sure you have rubygems 3.2.0 or newer installed. Run <code class="language-plaintext highlighter-rouge">gem update --system</code> to update your rubygem to the latest release.</li> <li>Run <code class="language-plaintext highlighter-rouge">gem signin</code> to create a new API key.</li> </ul> <p>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 <code class="language-plaintext highlighter-rouge">~/.gem/credentials</code> or <code class="language-plaintext highlighter-rouge">~/.local/share/gem/credentials</code> file.</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>$ cat ~/.local/share/gem/credentials :rubygems_api_key: rubygems_cec9db9373ea171daaaa0bf2337edce187f09558cb19c1b2 </code></pre></div></div> <p><strong>Note:</strong> The legacy endpoint to fetch API keys, <code class="language-plaintext highlighter-rouge">GET /api/v1/keys</code> 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.</p> </div> </div> </div> <div class="paginated-nav-links"> <a class="paginated-nav-link--prev" data-icon="<" href="/rubygems-org-rate-limits"> <span>Previous</span> </a> <a class="paginated-nav-link--next" data-icon=">" href="/run-your-own-gem-server"> <span>Next</span> </a> </div> </div> </main> <footer class="footer"> <div class="l-wrap--footer"> <div class="l-overflow"> <div class="nav--v l-col--r--pad"> <a class="nav--v__link--footer" href="https://status.rubygems.org/">Status</a> <a class="nav--v__link--footer" href="http://uptime.rubygems.org/">Uptime</a> <a class="nav--v__link--footer" href="https://github.com/rubygems/rubygems.org" target='_blank'>Code</a> <a class="nav--v__link--footer" href="https://groups.google.com/forum/#!forum/rubygems-org" target='_blank'>Discuss</a> <a class="nav--v__link--footer" href="https://rubygems.org/stats">Stats</a> <a class="nav--v__link--footer" href="https://blog.rubygems.org/">Blog</a> <a class="nav--v__link--footer" href="https://rubygems.org/pages/about">About</a> <a class="nav--v__link--footer" href="mailto:support@rubygems.org">Help</a> </div> <div class="l-colspan--l colspan--l--has-border"> <p class="footer__about">RubyGems.org is the Ruby community’s gem hosting service. Instantly publish your gems and install them. Use the API to interact and find out more information about available gems. Become a contributor and enhance the site with your own changes.</p> </div> </div> </div> <div class="footer__sponsors-wrap"> <div class="footer__sponsors"> <a class="footer__sponsor footer__sponsor__ruby_central" href="https://rubycentral.org/" target="_blank" rel="noreferrer"> Supported by <span class="t-hidden">Ruby Central</span> </a> <a class="footer__sponsor footer__sponsor__dockyard" href="https://dockyard.com/ruby-on-rails-consulting" target="_blank" rel="noreferrer"> Designed by <span class="t-hidden">DockYard</span> </a> <a class="footer__sponsor footer__sponsor__dnsimple" href="https://dnsimple.link/resolving-rubygems" target="_blank" rel="noreferrer"> Resolved with <span class="t-hidden">DNSimple</span> </a> <a class="footer__sponsor footer__sponsor__datadog" href="https://www.datadoghq.com/" target="_blank" rel="noreferrer"> Monitored by <span class="t-hidden">Datadog</span> </a> <a class="footer__sponsor footer__sponsor__fastly" href="https://www.fastly.com/" target="_blank" rel="noreferrer"> Gems served by <span class="t-hidden">Fastly</span> </a> <a class="footer__sponsor footer__sponsor__honeybadger" href="https://www.honeybadger.io/" target="_blank" rel="noreferrer"> Monitored by <span class="t-hidden">Honeybadger</span> </a> <a class="footer__sponsor footer__sponsor__domainr" href="https://domainr.com/" target="_blank" rel="noreferrer"> Verified by <span class="t-hidden">Domainr</span> </a> <a class="footer__sponsor footer__sponsor__whitesource" href="https://www.whitesourcesoftware.com/" target="_blank" rel="noreferrer"> Secured by <span class="t-hidden">Whitesource</span> </a> </div> </div> </footer> <script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-10315684-2']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script> </body> </html>

CINXE.COM

API key scopes - RubyGems Guides