Skip to main content
UX Strategist
Jul 19, 2016


Why is it so hard to register API keys on developer portals? Why is it so time-consuming to get started with an API?

To answer these user questions, we need to understand that there are two opposite intentions about running developer portals. On one hand, every developer portal aims to delight developers with a great product experience and to convince them to register as early as possible. The goal is to reach high conversion rates. On the other hand, companies want only trustworthy people to use their products, they want to avoid misuse. Such security considerations often lead to a painful registration procedure.

If you want to provide a better developer experience (DX) on your portal, you need to understand what makes developers like your portal. As a first step you need to discover how you can build up trust and how that would fit into the onboarding experience.

We wanted to understand the nature of trust issues and to figure out how we can overcome them in order to create a “frictionless” onboarding experience. Here is what we’ve found so far. We hope it’ll be valuable to both users and owners of developer portals.

The Structure of Trust

The Nielsen and Norman Group conducted a user research where they identified the elements of trust.

Consider trust as a pyramid (as opposed to the sales-funnel). On the lowest (and broadest) level of the structure, there is no trust established yet. Going higher on the pyramid, the level of trust is increasing. Applying this to the users of a developer portal, the research shows that when users meet the site for the first time there is no trust established yet. You need to help them climb the levels of trust.

>Sites must meet users' basic trust needs before they demand that visitors enter information or engage with them. Nielsen’s trust pyramid has 5 distinct levels of user commitment, each with separate design requirements before users will give a website what it wants from them. (Katie Sherwin NNG, 2016)

Let’s see the levels of the pyramid:

  1. Baseline relevance and trust that needs can be met: It happens when the user first meets with the site/application.
    They usually try to find the answers to the following questions: Could this site help me accomplish my goal? Is it credible and can I depend on this information? Does it seem to have my best interests at heart?
  2. Interest and preference over other options: Do I choose to use this site to accomplish this specific task? Is it better than other options?
  3. Trust with personal information: Does this site offer enough value that is worth the time and effort to register? Should I share my personal information with this site? Do I want to receive emails from this company?
  4. Trust with sensitive/financial information: Do I trust this site to securely use and store my sensitive data (e.g. credit card, street address)? Is it worth the risk?
  5. Willingness to commit to an ongoing relationship: Am I comfortable enough to establish a continuous connection with this site (e.g., recurring charge, linking with other accounts)?
The Pyramid of Trust

API key requests and trust

How the pyramid works in practice

Imagine yourself visiting a developer portal. On the front page, you see only a logo and the login/registration option. The portal is asking for user data without providing any information about its product. So you aren’t sure that you are in the right place, yet the site wants you to immediately start on the third level of trust. This goes against the reciprocity principle which says: give your users something before you ask for anything from them.

One of the possible solutions is a two-step process, in which the portal provides the basic information for its visitors.

To achieve the first step on the pyramid of trust, portals should include the following elements:

  • Headline and supporting headline: these elements explain the main concept and purpose of the site in brief.
  • Benefits: describe the portal’s services. The optimal number of benefits is three. Adding a short description to each will help users to understand these benefits better.
  • Representative images: the role of these images is to reassure users about the portal.

In order to build this trust further, take the second step by adding feedback about the portal from people outside of the company:

  • Social proof: feedback from users facilitates the visitor’s decision regarding registration. It usually shows appraisal addressed directly to the company.
  • Reference in social channels: similar to social proof, but this shows users’ opinions about the developer portals that they shared on the various social channels. It builds trust in visitors because they see individual assessment that isn’t addressed to the provider of the developer portal, but to the members of a personal social network.

According to the model, visitors will be on the third level of trust if this information is served correctly on the developer portal. So they are ready to share some personal information if the site provides services that meet their needs.

What developers say

Developers feel that the portals don’t trust them, so they try to find a loophole in the system. (Which implies that developers don’t trust the portals either.) These loopholes can help us understand how developers try to make the registration process easier.

Going to Hell for this

The biggest problem is that it’s too easy to loose the user’s perspective while you keep an eye on security.

Identity verification

Email address

A possible solution is that the portal provides developers with the possibility to request an email address as part of the authorization process. Developers can use the same email address to reach every company product or service – this way they don’t need to re-enter information in order to sign in or sign up for new services (for example Dwolla uses this method).


Another typical solution is the system asking users for a micropayment as ID-verification. For example, a one dollar transaction to verify that whoever wants to register for an API key is already authenticated by a financial institution. For this, the user has to be already on the 4th trust level out of five. So to use this solution, one needs to address all the previous levels carefully. However, the developer needs the key fast.

Site registration

Where product owners are not worrying about security problems (depends on the business model), developers could generate as many API keys as they wanted after accepting the Terms and Conditions (like GitHub, Digital Ocean). Registration to the site is still a prerequisite, which is equal to level 3 on the pyramid.

Using mock APIs

If a developer puts data into the API, then the most important thing is the opportunity to try out how the API could be used (mock API). This way, developers could find the best solution. A trial period may help in these cases. During this time, they can become familiar with the process. As they put data into the API, it’s not worth creating a new account every month for a new trial period, so likely the developer will register when the trial period ends.

Another typical case is when the company itself offers data through the APIs and the user just queries it. In this case, the users may prefer a limited demo account with which they can find out whether they can get the desired data.

The last two processes require only level 2 trust from developers: interest and preference, no personal information yet.

Information builds trust

Based on what our developers suggest, we found that the reason for their mistrust is often the lack of information. The right information could build their trust step-by-step. The registration process should be quick and easy. If high-level ID verification is essential, we need to guide our users-to-be through the steps of trust with UX solutions.

Good design can build trust

A developer portal should be designed to be self-evident and professional:

  • straightforward navigation,
  • appropriate and clear communication (e.g. consistent terminology),
  • no typos, no broken links or such mistakes (they swiftly decrease credibility).

Addresses the 1st level on the pyramid

It is also important to be connected to the rest of the web. Due to the increasing amount of social media and review sites available, people have learned to trust rather these external sources than company-sponsored content. People often read the reviews before deciding which company would be the best for them. For this reason, it is crucial to have a presence on external review sites. It communicates how transparent and confident the company is about its services.

Addresses the 2nd level on the pyramid

Being comprehensive, correct, and current is a proof of professionalism which builds trust quickly. The portal should suggest that the company:

  • is well informed and committed to helping its customers
  • has a full range of services or products

Addresses the 3rd level on the pyramid

Upfront disclosure fulfills the reciprocity principle. Visitors don’t have to give any kind of information before the portal provides them with some value. If users can get all the information they need for making their decision before registering, the process is also transparent.

Addresses the 4th level on the pyramid


Most developers are not aware of the nature or origin of their doubts. That’s why we can’t research the trust issues by simply asking for user feedback. We have to observe their actual behavior. However, the trust equation is easy: the more information we ask the more trust we need to establish beforehand. It means if we need a higher level of personal information, we need to build up the user’s trust to the specific level. So users can feel they are in control. The good thing is that the basic factors of site trustworthiness are the same, regardless of location or culture.

(Written by: Katalin Nagygyörgy
Fact-checked by: Tamás Demeter-Haludka
Edited by: István Zoltán Szabó

*We would much appreciate your feedback. Do you agree that it is mistrust that degrade the Developer Experience on many developer portals? Got a story to share? Leave us a comment below!*

Would you like to be notified when we publish articles about Developer Portals? Subscribe to our newsletter.

Kata is a User Experience Strategist. She collaborates with developer portal customers to define architectural decisions based on their business strategy. She also provides them with possibilities to make sure the product communication resonates with current and future users, mostly developers.

As a psychologist, she is passionate about research methodologies and gamification. She has a Ph.D. in psychology for which she did research into the motivational background of online gaming.


Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.