Product case study | Turn-key user management for no-code API portals
Client: Greymatter*
Goal: Improve coverage for customer needs
Project: User management for no-code API portals
Notable launch impact: 8,000+ API consumer sign-ins per month
*Name has been changed to protect my client’s integrity
The product
Greymatter’s no-code API portals are a turn-key (as in, push-button-receive-website) tool to allow API producers to quickly document and publish their APIs to their consumers, and manage who has access to them.
[I’ll try to define some of the obscure industry words as we go; think of an API provider, or producer, as one of our customers who design, build, and publish APIs — in short, they produce APIs for their customers; an API consumer, then, is one of their customers, who are usually 3rd-party or individual developers.]
For our two personas, the Portals platform has two separate interfaces:
- A no-code CMS tool for API producers (API developers or API program managers) to create, design, and manage their public-facing API catalog. Producers can publishing/un-publishing API marketing pages, support details, API documentation, and manage keys and entitlements. Colloquially, Greymatter calls this the “admin UI”.
- A public-facing, white-labeled portal for API consumers (Greymatter’s customer’s customers) to register for API keys, manage their access to our customer’s APIs, and learn about these APIs by trying out live API calls and reading documentation. Colloquially, Greymatter calls this the “portal UI”.
This is pretty hard to visualize, I’ll admit. It gets extra complicated when you factor in all the runtime/management layers of Greymatter’s API platform. Here’s an IA diagram of what it all looks like:
[An aside on IA, or “information architecture”: if you don’t understand your IA, your users definitely won’t!]
The parts I’m focussing on here are the portal user UI (green) and the portal admin UI (red).
The challenge
At the time I began working on minting a UX team at Greymatter—some time around late 2014, the only “API portal” for customers to publish their API catalog was a heavily customized monolith built on top of a popular (c. 2011) web-app CMS/framework. This tech stack, while highly flexible and extensible, was costly to maintain, and required knowledgeable developers to make changes—resulting in a high TCO for both customers and Greymatter. To make things even more interesting, the hosting of these portals was contracted out to a 3rd-party, which made understanding and managing operating costs, and supporting users, difficult.
Looking to the future, and considering an end-of-life approaching for the monolith’s framework, Greymatter had to start looking at other options. They needed a simpler, more cost-effective solution that could meet the needs of 80% of their customers, out-of-the-box. This led to a small team of [rebels] getting together to build out a new, light-weight, turn-key alternative. It wouldn’t ever be as extensible or flexible as the framework-based portal, but its rigidity meant it would be great for most customers.
I began running point on UX for Greymatter’s API consumer experience products around late 2016 as they were preparing to launch the first beta of their new integrated portals. Although customers were excited to try the new platform, it fell short in many areas, and very few were able to make the switch. Key features were incomplete, unintuitive, or missing entirely. Thankfully, we didn’t give up there.
We set out to understand which missing features were mission-critical for our users, and what of anything we’d built already was broken. Rounds of qual interviews and community feedback all pointed to one thing: the way we handled identity and security wasn’t secure, robust, or functionally reliable enough for our enterprise customers. [The at-launch method of “authentication” was to use a time-bombed transactional email verification link to identify users instead of a trusted authentication service.]
- Consumers needed a way to manage and share their API keys (and entitlements) with the rest of their team, and they wanted a secure way to self-service their access (things like rotating keys, sharing/revoking access, and deprecating old keys).
- Providers needed to be able to govern access to API documentation and runtime at the user, team, and company level.
Our challenge: We need trusted user-level identity and access management, with collaboration tools for teams and sharing.
And what good is a challenge, without a goal to help you meet it?
Goal: Design and build an identity platform that can scale for thousands of users, with username/password (or federated SSO authentication), per-entity sharing & security for consumers, and powerful administrative controls for producers.
Designing the identity provider service
The importance of proactive design, or why you should invest in design thinking and methodology
As an engineering-first startup, Greymatter had been reluctant to commit resources to “proactive” product design through research, discovery, refinement, and validation (well, and follow-through, but that’s another story). Having recently been acquired by a big you’ve-probably-heard-of-it company, this project might have been an opportunity for a radical shift in design methodology: to building products with a battle-tested design-first approach to solving big product problems. But as I would continue to be reminded of, great design is a culture, not a process. It would take another 4 years before Greymatter would finally orient itself with a design-first mentality.
What does design-first mean exactly? Consider the difference between proactive and reactive design. On the former, we have a great way to tackle something big and uncertain: you (what I like to call) “front-load” your design work, doing as much up-front work to create a wholistic view of the next 18–24 months of the product. You want to do this as many weeks in advance as you can before engineers are scheduled to start working on it.
Design-first lets you do things like build a user journey map and work with users to validate and prioritize scope. Put prototypes together (in a time before Figma, before InVision, when prototyping was a very labour-intensive process) and test ideas with users. Backed with data, you’d be confident that you were on the right trajectory. Once you shipped a feature or two, you’d need to become somewhat reactive—you’d need a process for handling user feedback, bugs, and things you missed the first time around.
But it wouldn’t take away from your proactive product design/development cycle. You can do a refresher once a quarter to react to feedback (research), change in business objectives, or new user requirements, and adjust course accordingly. This makes sure everyone on the team (and stakeholders) are on the same page, can commit to objectives, and can easily carve off how we get there in a very optimized, prioritized way. As you get a cadence going, you can build a culture around proactive product and design discovery work long before your engineers are ready (think a quarter or two) so they’re not twiddling their thumbs waiting.
Of course, none of that happened on this project.
Instead, I had to run the old “beg forgiveness” tactic to organize and facilitate a design sprint. We crammed all of our discovery into just three days. The team worked ridiculously hard to put together our best ideas of what we need, what the IA might look like, and some very basic wireframes of concepts.
Exploring our problem space & influencing architecture decisions
Along side our design work, there were some big picture eng/product decisions that needed to be made, too. It didn’t take long before the team realized that this was not one of those “roll-your-own-identity” situations. We spent a good part of our sprint’s discovery time looking at open-source auth platforms that we might build a UI on top of. Pretty hard to pick one when you aren’t really sure about your users’ requirements, though? We had to use our intuition to choose a platform, instead of researching questions like these, which might have had a material impact on our decision:
- Do API producers need to have the same identity pool span across multiple portals?
- Do API consumers really need to have teams and a hierarchy of permissions?
- Do we architecturally need one identity service provider for all our customers’ portals, or do we need to spin up a dedicated instance for every customer? Every portal?
- Do we need federated (SSO) auth for other identity providers?
- What are the legal and data residency concerns we’ll need to meet?
One of the products shortlisted that checked most of our boxes was CloudFoundry’s UAA platform. An added bonus was that the team was already familiar with it, because it powered Greymatter’s own internal authentication/authorization. That would make for good supportability.
We went with it.
We got lucky going with our gut here — it wasn’t until after the sprint, after we’d already made the decision, that I had the time to learn about UAA and its capabilities, to test whether my rough design sketches would map to its features, and to understand how it could/should fit into the Greymatter ecosystem. Had we guessed wrong, it would have been quite the investment to walk back from (or more likely, we’d be stuck with it). From reading UAA’s documentation, I experimented with a sandbox deployment, making sketches and design notes along the way. I also collected examples of other user management systems around the web to help with ideation and to make sure we weren’t going against the grain. From a UX point of view, UAA really did support the vision that came out of the sprint, but that’s not the kind of gamble I want to repeat.
One of the questions we tried really hard to answer during the sprint (without data to back it up though?) was “do API producers need to have the same identity pool span across multiple portals? One for each portal? One for everything?”. We should have answered all these questions first, backed with data. But eng was already blazing ahead writing code for a POC that didn’t meet our design needs, which meant cutting corners as we reacted to changes IA/API design, trying to keep up with a POC with a mind of its own. We (UX, PM) made a call, but in the end, it was an expensive mis-step—we later pivoted to a simpler model. It wasn’t even because it was the right thing to do, but because we were so busy reacting to small fires, the entire product felt rushed and unfinished.
Hard lessons
Unfortunately, you’re as likely to be wrong going with your gut as you are likely to be right. We got what we wanted, but at a cost. Eng had argued that we should build one identity “zone” per-portal (1:1), because anything else (1:n or n:n) would introduce too much complexity (and you’ll remember we didn’t have the data to prove it whichever way). Turns out, they were right. We should have spent the time to make sure the design was polished, and edge cases were accounted for. We didn’t, and in the end, they replaced the 1:n zone:portal model with a 1:1 model.
And that wasn’t our only hard lesson. We ran into a mudslide of blockers along the way, like a brand-new, unfinished, untested design system (with a passive-aggressive, micromanaging gatekeeper); legacy architecture decisions we had to tiptoe around; a lack of users to test with; weird edge cases we hadn’t considered, many a byproduct of poor IA decisions. In hindsight, we (I) really should spent more time building less, better.
We lost, taking the design shortcuts we did. We added layers of complexity to an already ambivalent directive (which, mind you, should have been clearer than mud in the first place). Most of our ideation was done via ad-hoc and unstructured planning sessions — many spread out over weeks or months. We had no rhythm, no cadence, and no process. This led to a breakdown of goals, priorities, and requirements because it impaired our ability to agree on things and make decisions. Ultimately, it hurt our product.
What I still want to know is: was this a breakdown in communication? Leadership? Ego/hubris? I’m still not sure, but it’s a question I’m reminded of ever since. When things are going sideways, it’s important to understand which of those three reasons is to blame. I know there was also some considerable engineering turnover during this time, so I can imagine not having an owner—someone accountable for their decisions—was also a factor.
In the weeks following the compressed design sprint, we each (PM, UX, and the engineers) were left with a fragmented idea of what was important. By the time we reached a consensus on what to build and how it might behave, many decisions had been lost or overruled, design ideas were misunderstood or miscommunicated, and considerable time and effort was spent revisiting the same solutions.
Post-launch, a retrospective would eventually lead to a more serious commitment from leadership to invest in up-front design thinking and structured product planning and design reviews. The hope was that we should be able to align on big decisions early, and make sure regular checkpoints would keep everyone on track, and accountable. But steering a ship is hard — it’s 2021, and though we’ve improved greatly, even today we still struggle with this from time to time.
[It’s also worth noting this was a distributed team with an odd dynamic: both of the UX designers (including me) attached to this product were 100% remote; all of the engineers doing the work were in a satellite office, and the people actually making product/budget decisions were back in the Bay Area office. I don’t know how much our remoteness impacted our success, but post-COVID, it’s clear that it takes the whole team to make it work.]
On-boarding a new design system
During the weeks we spent trying to agree on what to build, a parallel effort was underway to update all of the Greymatter product with a universal design system. (It’s a funny story, really because it already had a design system, but because no one wanted to create reusable web components, every team rolled their own UI, and the appearance and behavior varied wildly from page to page. You can think of it kind of as the Wild West of web applications).
I can be honest though that the original design system, in all of its implementations, was deeply flawed. For this, I am partly to blame. And passionate I am about design systems, though, so of course I had made myself a contributing member of the team that was working to improve it.
Why is this relevant, you ask? Well, see, I agreed to let this project become the first test subject. [Pausing here to let you roll your eyes at me.] Unfortunately, trialing each incremental design system change meant constantly tweaking and changing superficial/cosmedic things. On top of the actual design work to make the changes, constantly waiting for the design system team to review and discuss added a ton of overhead. Onto an already time-stressed project. Several ground-up redesigns later, and after dozens of (inconsequential) cosmetic changes, we’d caused a cascading delay on eng deadlines. And as I’m sure you can imagine, I got the short end of the stick.
Refining scope & prototyping
Rewinding a bit, we’re sitting chronologically somewhere around 6–8 weeks after the design sprint. Having burned through so much time in the early weeks of this project, the very slow progress on the design system, and an immovable (of course) release date, meant I needed to start aggressively looking for features to rip out which would still leave us a more/less intact product. That wouldn’t leave us much time for Product Excellence, or quality and polish, either. It was important to me that we didn’t just ship an MVP (“it works, ship it”) but an MUP (minimum useful product). Challenging, because with nothing but our instincts to go on, we were at risk of removing something critical. Like we couldn’t very well cut user sign-ups and account management; users would still need a secure place to view their entitlements (apps and credentials that belonged to them). These were P0 (priority-zero) features. But maybe collaborating with other teams, sharing and granular permissions of entitlements, and the fancy usage metrics dashboard could be left out?
I don’t always sketch on paper, but these were the days before I had an iPad to scribble on (I don’t anymore, and I am sad); sitting on an airplane, this was what I had to work with. While I knew that we were going to be pulling features left and right, it’s still important to keep an eye on where you’re going. I wanted to document that “grand vision”, so I sketched out a few of the views with the future in mind. This sketch of the admin view is actually a snapshot in time of one of the design system iterations; many of these principles can be seen in the final mocks, but there are some notable differences.
You’ll notice the breadcrumb Consumers > Default zone, implying we’re looking at a “detail” view of an identity zone (a self-contained, isolated pool of users and teams). Remember too we want to allow mapping an identity zone to multiple portals (allowing the same users, with the same credentials, to log into however many portals were attached to a zone) so you can imagine a list view of all of them living a level up from here.
Here’s a Balsamiq version based on the original sketch.
You can start to get a feel for the level of complexity things were beginning to reach; this thing was a beast. It was even spilling over into the navigation — causing problems with 3- and 4-level nested pages, yet another setback we would have to face.
In this wireframe, you can see, too, how busy the relationships were between other entities — a list of portals connected to this zone, a list of configured identity providers. [An identity provider in the UAA sense is basically an endpoint where users can be authenticated, each containing an isolated pool of users). We started with a basic “built-in” user pool, but the team eventually added support for SSO, and might one day support OpenID, like “Sign-in with Apple or Google”]. And for each of these connected entities? We needed controls for users to attach, detach, create, delete, and edit related entities (and with varying levels of access, depending on a user’s role or access level).
At this point, we did make a final decision to cut Teams and Audiences from the launch, which thankfully didn’t require much UX work—just dropping a couple of tabs, really. Easy.
Or, well, it would have been, if not for that pesky design system. There was a power struggle, some egos got bruised, and some organizational changes happened, all of which compounded to make getting from this wireframe to a launched product take way longer than it should have.
The final design, a what-if
It’s remarkable that I spent a comparatively tiny amount of time (just a couple of hours) re-imagining the design system, and creating mocks based on a what-if. Why did I do it? Because I needed something shiny for my portfolio, and to this day, I think the (unfinished) design system we ended up with is embarrassingly bad. So instead, I made these, and you get to enjoy them, too.
The cool thing is that in the end, we did finally ship this thing (even though it didn’t look this good). When I departed the project, we had more than 8,000 user sign-ins per month — a win!
Experiences like this helped me become a better designer
For designers, it’s inevitable that we spill over and learn things beyond our immediate job title. Just like great engineers need to understand their users, and product managers need to understand engineering costs, you can’t design great products by remaining ignorant to the business of building software. Things like Magic Quadrants matter; engineering costs matter.
So what did I learn from all this?
- You need time to make good design decisions, early. That means your leadership committing to and investing in whatever your team needs in order to make critical scope decisions well before engineers are ready to build. Something about the metaphor of not changing a tire while the car is in motion?
- Design systems are hard. Don’t make your production work dependent on design system decisions. Part of the reason we did this was lack of eng (or eng leadership) commitment to anything related to reusable components, so we thought we could be clever by piggybacking design system work onto an ongoing project. This was terrible. Don’t do it. If you want a design system, you need eng director-level buy-in, at least one engineer dedicated to building design system components, and you make sure you get all the wiggles out before you start building with it.
- Back up your opinions with data. Bias in tech is real—made in California, by opinions. And in our case, no one could even agree on what to build, how to build it, or why it mattered. We just wasted so much time circling our drain of opinions. Countless irreversible assumptions are still evident in the product today, which has become technical debt that may never get fixed. Sometimes it’s better not to sweat something too big when you have no data; just do your best to get something out the door that someone will use. Remember that MUP—minimum usable product? Aim for that, build small, and then learn from your users.
fin
— B
read more long-form at brandonscript.design
follow me on Twitter, Polywork, or LinkedIn
work with me at pacificaviator.co
