Get Started

Authenticating Into ReadMe’s CLI With 1Password and Your Fingerprint ☝️

Long-time followers of the ReadMe blog know I have been absolutely shameless in my love for 1Password. It's a great password manager that we use here at ReadMe to securely store shared logins, API keys, and more. Staying secure online is increasingly difficult these days, and we’ve been able to safely rely on 1Password for best-in-class security with a convenience and user experience that lives up to one of our core ReadMe values: “strive for simplicity.”

So it should come as no surprise that I’m very stoked to announce ReadMe's partnership with 1Password. With the ReadMe shell plugin for the 1Password CLI, together we’re making your experience with ReadMe’s developer tools even more convenient and secure. Get the details below! 🤝

Juggling API keys: a necessary DX evil 🤹

Let’s first start with some background. Over the last year or so, we’ve been making several improvements to the developer experience around API keys in ReadMe:

While these changes have been great from a security and developer experience standpoint, none of these could possibly address a common problem amongst developers: juggling lots of API keys. Figuring out where keys came from, rotating keys, maintaining separate keys for separate environments/users…the list goes on! It’s a necessary evil for developers when a key inevitably gets leaked 🙀

The Getting Started and Authentication pages in the API reference 🔑

Our knowledge base has grown to the point of switching over to a multi-project setup for our docs. Because of this, we’re now working with many API keys across several ReadMe projects, which is also the case with many of our Enterprise customers. And once you start dealing with multiple API keys that you’re sharing with your team, it can get chaotic rather quickly.

1Password has proven to be a useful management tool for API keys not only because of its security, but also because you can jot down notes for a given API key. You can use this to provide helpful context for fellow engineers, like expiration dates, links to management dashboards, where it’s used, etc. While it’s easy enough to store these credentials in your password manager, what about using your password manager as the single source of truth so you can load secrets into your developer environments in a secure, automated way?

When adding an API key to 1Password, include detailed notes for context — your fellow engineers will thank you!

Luckily, 1Password introduced shell plugins, which are integrations that securely pass API keys into your favorite command line tools, including gh (the GitHub CLI), twilio (the Twilio CLI), and (you can probably guess where I’m going with this…) rdme (the ReadMe CLI)! Let’s dive into the ReadMe shell plugin below.

Say hello to the ReadMe shell plugin 🐚

With the ReadMe shell plugin set up, you can keep your ReadMe API key in 1Password and securely pass it into your rdme commands. What does this look like in practice? A quick scan of your fingerprint (if you’re a macOS user):

0:00
/0:15

Pretty slick, right? Let’s walk through how this all works:

  • First, make sure you have the latest version of rdme, the 1Password desktop app (Mac or Linux only), and the 1Password CLI (version 2.12.0 or above) installed 💿
  • Next, set up the ReadMe shell plugin for the 1Password CLI. This will create (or import, if it already exists) a 1Password item that contains your ReadMe API key 🐚
  • Once everything is set up, 1Password CLI will listen to your terminal for rdme commands that require authentication (i.e., authenticated commands like rdme openapi are listened for and non-authenticated commands like rdme --help will be ignored) 👂
  • When a rdme command is executed that requires authentication, the 1Password CLI will prompt you for your fingerprint (or whatever authentication setup you have for the 1Password app) ☝️
  • The 1Password vault is unlocked, your ReadMe API key is securely passed into the terminal command, and rdme is connected to your ReadMe project 🚀

While this approach to passing credentials into rdme is both convenient and secure, do you want to know what’s my favorite part about this experience? If you’re juggling many API keys across several ReadMe projects like we are, you can store all of them in 1Password and have the ReadMe shell plugin confine your credentials to a specific directory or terminal session.

With the ReadMe shell plugin, you’ll be an expert API key juggler in no time!

Some bonus “action” 🎬

But wait, there’s more! As an added benefit of securely storing API keys in your 1Password vault, you can safely load them into CI/CD environments, like GitHub Actions. This is great news, because rdme happens to have first-class support for GitHub Actions!

Here’s yet another great example of how 1Password and rdme can work together in harmony to securely sync a directory of Markdown files to ReadMe:

# Runs on every push to the `main` branch
on:
  push:
    branches: [main]

jobs:
  sync-to-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Load secret from 1Password
        uses: 1password/load-secrets-action@v1
        with:
          # Export loaded secrets as environment variables
          export-env: true
        env:
          OP_CONNECT_HOST: <Your Connect instance URL>
          OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }}
          RDME_API_KEY: "op://engineering/readme/api-key"

      - name: Sync OpenAPI file to ReadMe 🦉
        uses: readmeio/rdme@v8
        with:
          # `rdme` automatically reads the `RDME_API_KEY` env variable
          rdme: docs ./documentation

Let’s break down what’s happening in the example above:

  • This workflow kicks off when a commit is pushed to the main branch of your GitHub repository.
  • 1Password’s GitHub Action establishes a secure connection to 1Password, grabs the ReadMe API key value and exports that as an environmental variable called RDME_API_KEY.
  • The rdme GitHub Action automatically detects RDME_API_KEY as an environmental variable containing your ReadMe API key, and uses that to sync your Markdown docs (located in the documentation/ folder) to your ReadMe project.

With the power of 1Password and rdme, you can securely sync your docs to ReadMe — whether you’re working in the command line or in a GitHub Actions runner 😌

Now let’s get you plugged in 🔌

Ready to start syncing? The integrations described above are available now:

We’re always looking for ways to make ReadMe’s developer tools safer and more enjoyable to use. If you have any feedback about your ReadMe experience, feel free to reach out to us at support@readme.io or open up an issue in the rdme repository. We’d love to hear from you! 🦉

Recommended next reads...

Stay In-Touch

Want to hear from us about APIs, documentation, DX and what's new at ReadMe?