WordPress: Keyring Developer’s Guide

Download Keyring from the WordPress.org Plugin Repository.

Keyring is a generalized framework for WordPress which handles authentication with, and authenticated requests to remote services. It provides a set of predefined “Services” which describe how to communicate with a collection of popular platforms, and also makes it easy for you to plug into that framework and define your own Services for other systems.

Written as a plugin for WordPress, Keyring may be run in “headless” mode to provide completely white-labeled authentication/communication functionality, or with a simple UI to allow users to manage their connections. On its own, Keyring does not “do” anything useful for an end user. It is built purely with the developer in mind, to make your life easier when integrating with other services. Using Keyring means you no longer need to care about OAuth or HTTP Basic, or how to sign requests or anything else — you request a secure connection from Keyring and if one is available, you will be provided with a simple, standard way of talking to that service. If there is no connection available, then the user will be taken through any authorization process and then the finalized connection will be returned to your plugin upon completion.

In this documentation, we’ll look at the architecture of Keyring, how the pieces work together and how you can extend Keyring by writing your own Services and Token Stores, plus implementing it as the authentication/communication layer in your own plugins/themes.

What do you think?

  1. Ryan said:

    awesome! i’ve been working on a similar project for a while. it imports your posts and other content from facebook, twitter, etc. into blogging platforms like wordpress, tumblr, and blogger. it doesn’t dive as deeply into wordpress in particular, but trades that for breadth across the other destination platforms.


    it uses another project, https://github.com/snarfed/activitystreams-unofficial , to translate the data from each source platform to a common format (ActivityStreams), before converting it again to each destination format.

    i’m glad to see more people working on these kinds of IndieWeb projects!

    • Beau said:

      Nice work Ryan! I was involved with the ActivityStreams spec team way back when, so have been interested in this stuff for a while 🙂

      I see you’ve done some work on pulling in comments/conversation happening around your content on other networks as well — I’ll be looking at doing that with Keyring/my importers at some point.

      Stay in touch!

  2. Peter said:

    Hi Beau, great job! this plugin is awesome! just what i needed.
    A little question, i looked but i have not found, what is the license of the plugin !?

    • Beau said:

      Thanks, and I really should add the license into the docs 🙂

      It’s GPLv2 or later, per the requirements to be in the WP.org plugin directory.

  3. Beau, just a question for a work-around
    (I am not that smart myself within PHP)

    – I seen in the code that it is checking on images being imported already.

    That’s a problem for me when I want to import in 1 blog my wifes instagram pics and my own instagram pics (we have a project with a hashtag and we want to import all instagram pics with that hashtag.

    Your plugin does import all my images properly, with a very very nice date save, tags etc.. perfect !

    But after the import of my +900 pics (thats working after fixing a fcgi issue)
    images of my wife are seen as duplicate (25x) and all other images are not retrieved.

    It would be awesome if I could import those images as well

    any hints, tips / work around how to achieve this?

    Thanks for this wonderful plugin so far 😉

    • Beau said:

      It sounds like you’re using the Keyring Social Importers, in addition to Keyring. I guess it’s hitting a full page of duplicates, and then bailing from checking the rest, because it doesn’t import anything in a full batch?

      As a hack, you could try removing the check in keyring-importer-instagram.php around line 226:

      // If we’re doing a normal import and the last request was all skipped, then we’re at “now”
      if ( !$this->auto_import && self::NUM_PER_REQUEST == $skipped )
      $this->finished = true;

      Remove that whole block, and see what that does for you. It might leave you in an infinite loop though, so you’d need to manually bail out of the import.

      • Correct, I am using that plugin.
        The loop is working, but not any import.
        the problem seems that there are already 921 instagram posts (from user1)
        that import *the initial one* was working flawlessly.

        Now I am finished with one user, and I need to switch to the 2nd user cause in that account I have also around 500 instagram posts which I have to import before I can make a selection what I do not need.

        I delete the information from the keyring from that user, than I add the info from user2, I have also made credentials/secrets under that account on the developer site of instagram. I am authenticated .. now I press import
        but still 0 images to be imported.

        (unfortunately) .. ;_)

        • Beau said:

          Ah, I think I see what’s happening then; it’s because basically the importers are currently written assuming only a single user. I need to make some pretty significant changes to support simultaneous users on the same blog unfortunately.

          Off the top of my head, the only way I can think that you might be able to make this work is to import everything on a different blog entirely, then export all of your posts/media, and import that WXR/WordPress file into the main one.

          I’d have to have a think about exactly how to support multi-users.

          • np,
            just after writing above I installed a new plugin DsgnWrks Instagram, seems to do the similar. BIggest issue was if the plugin is importing the image with correct date.

            So if you have spare time, otherwise … ;);-) .. thanks for feedback !

  4. Ivan Ferrero said:

    Hi Beau your plugin seems very promising!
    I just installed the Social Importer plugin and created a Twitter App.
    Now I’m ready to import my tweets.

    Just a question: do I have to import all the previous tweets?
    They are more than 10K!

    Can I import only the new ones (or the tweets I’ll post from this moment on)?

    How about the other Social channels?


    • Beau said:

      Currently, it’ll go ahead and want to import all your older posts. Things could probably be modified to just start from “now”… that’s a good idea. They all do the same thing, so they’ll all try to download all your older stuff before getting any new ones.

      • Ivan Ferrero said:

        Beau thank you for your fast reply!

        So I don’t have a chance to not import my old tweets at the moment, is it?

        I think I found a workaround to this: I may create a temporary category and let the import to end, then I delete all the posts of this category.
        First I have to decide whether my tweets would be of any value to my readers: I may keep just a widget with the stream. 😉

        The issue comes when we talk about my RSS (i.e.: G+): will the plugin import ALL the posts?

        If I may suggest you two features:

        1) the option to import only the new posts

        2) the option to import the posts as draft

        Just another question: I had a look around this site and found a very beautiful stream with maps and tweets (that seem to be embedded).
        Is this the effect of the plugin?
        Will I see the imports like this on my site too?
        Otherwise: how did you achieve this look?
        This is very interesting!

        TNX again!

        • Beau Lebens said:

          Correct: you cannot prevent it from importing your old posts currently.

          The idea of importing as drafts has come up before, so that should be pretty easy to allow. You could also probably write a pretty simple filter/plugin that would do that for you (the importers allow you to filter things relatively easily before they’re imported/created).

          Importing new stuff only seems reasonable; just starting from “now” when you set things up.

          The maps and tweets you see on this site are all powered by the data that’s imported using the importer plugins, but the actual presentation and rendering and whatnot are controlled by this theme (Homeroom, which I also wrote). There are plugins that will leverage the geo data (as an example) which the importers store for each post where it’s available, but out of the box you won’t get any maps or any visualization.

    • Beau said:

      Keyring doesn’t really care what format the data is in, but yes, there are default handlers in place for JSON since it is the most popular format (especially for OAuth2/more modern APIs).

  5. The Future of the Web – Beau Lebens

  6. Xavier Roy on Twitter by Xavier Roy (Twitter)
    “@khurtwilliams Have you tried Keyring Social Importers? It does a pretty good job of importing from Instagram.”
    Foursquare import to WordPress with modified Keyring Social Importers code. Thansk to @xavierroy for the suggestion. #IndieWeb #PESOS #Foursquare #WordPress

  7. Keyring 3.0 – Beau Lebens