There is a weird mix of pros and cons when it comes to requiring pre-registration of API keys (where you go to a developer portal and identify yourself, agree to terms of service, etc).
Ever since Joseph Smarr and co. laid out the tangible dream of Portable Contacts: “you should be able to walk up to any web site, and tell them where your contacts are stored, and they should just go and fetch them” I’ve been wondering exactly how this will be achieved in reality when most service providers require pre-registration for their use of APIs.
A great solution requires good technology and workable business/compliance terms.
After a person responds to the question: Where are your contacts? with www.randomsocialnetwork.com the API and delegation endpoints are discovered using XRDS-Simple. This is very cool, the service provider can move the endpoints around and it won’t break relying parties.
With the ability for relying parties to dynamically discover new service providers, this makes it near impossible to require pre-registration of API keys/consumer keys.
At the Internet Identity Workshop #8 this week I proposed a session unconference style (by sticking a piece of paper to the wall) and to my surprise a big group of awesome people showed up. Representatives from big companies (Microsoft, Google, Yahoo!, MySpace and Facebook) and other smaller companies were there.

In the session we talked through the problem and talked through 3 scenarios for further investigation:
- 4th parties and widgets (e.g. JS-Kit, DISQUS) – a developer needs to configure the widget with API keys. The developer is present at the keyboard.
- Unattended registration with services – an end-user essentially introduces the third party to the service and no developer is “present at the keyboard”
- Data rights – when consuming data from any third party you need to know what is allowed with that data to in compliance with their terms of service.
Below is the notes from the session with some additional commentary/notes
We broke the session down into the following sections:
- What are the benefits of pre-registration
- What is the current pain
- Who is already looking at automatic registration of API keys
- What are the solutions
- How will this be abused
- Moving forward
What are the benefits of pre-registration?
There are many reasons for the service provider why pre-registration is great. I break these down into 3 areas: protecting the business, protecting against evil and providing value added services
Protecting the business : Accountability / Business Model
When a developer calls an API there is a certain level of accountability which the developer needs to agree to. This is usually done via Terms of Service acceptance and providing contact details.
I am not a lawyer, but as far as I can tell, most companies require an explicit developer action (E.g. clicking a tick box) to show agreement with the terms of service.
The service provider needs to have contact details for the developer to reach out to them. This could be things such as notifying customers of API updates, notifying of updates or even capacity planning (and removing throttling upper limits). In my opinion, using the tech-support contact information on the domain is unreasonable.
Protecting from evil: Reducing Abuse / Spammers
Opening any type of resource for programmatic access opens the door for abuse. By requiring developers to go through a manual step (and perhaps even completing a CAPTCHA/Human Interactive Proof) this drastically reduces the ability for nefarious actors to create hundreds (or thousands) of evil sites which “fly below the radar” of normal abuse detection.
This abuse could range from spamming to business model bypassing.
Providing value added services (different strokes for different folks)
Not everyone who calls API needs to be treated the same. Once you know a developer is a real person (i.e. not a bot) a smoother user interface (less warnings) may be presented to end users; access to additional “offers” / pieces of functionality can be accessed.
Providing analytics back to the developer on the number of end users who have granted permission to your application, or combining that with anonymous demographics on the audience can be invaluable to developers.
What is the pain being felt today?
Pain is relative.
Starting with the customer (end-user), the pain is: I want to be able to get to my data no matter where it is, even if the two services don’t have a pre-existing relationship.
For the developer pre-registration is sometimes challenging because:
- Development/QA/Production environments often require different API keys, and managing the deployment process is often difficult.
- If your service consumes data from 10 address book services, 5 photo storage services, 3 status services this is time consuming to onboard each different website (this requires a big assumption that protocols are standardized and the code is reusable for each type of service).
- For 4th party scenarios, the developers are often forced into the API key equivalent of the Password Anti-Pattern, where API keys are often copied and pasted into a third party service.
- The identities which are used for API key registration are essentially “service accounts” but are often just the developer’s real production account.
- Proving you own the domain by putting something in the root of the domain is challenging.
- Developing behind the firewall and creating “fake” fully qualified domain names reduces developer productivity.
- The barrier to entry for developers who just want to “kick the tires” is higher.
For services (which expose APIs):
- Getting wide spread usage of APIs can be limited due to the requirement for manual provisioning.
Who is already looking at automatic registration of API keys
No one today has the perfect solution.
Facebook are the closest for the 4th party scenario. Luke Shepard outlines the scenario where a developer is configuring a 4th party service/widget and pop’s a new window to Facebook (using their real identity) and the API keys are emitted to the screen. The developer then copies and pastes the keys back into the 4th party.
Ari Steinberg from Facebook talked about an interesting concept where all of these “programmatically created API Keys/App IDs” are grouped under a parent application ID. The scenario he outlined was there are some apps which allow you to create quizzes. The users may just want to block all quizzes from the same “manufacturer” even though they have different API keys.
Apparently there are a few other solutions which are somewhat close to working but we didn’t drill deep into them;
- OAuth discovery draft 1 apparently had provisions for similar functionality but this was removed from later drafts.
- Open ID / OAuth hybrid had some similar functionality
Google has a few solutions for non-provisioned OAuth : anonymous/anonymous which allowed for developers to use the APIs without pre-registration and was keyed off the domain.
What are the solutions discussed
Beyond what Facebook already has (which was agreed as the most promising for the 4th party scenario) we discussed a few more things to be investigated when provisioning is required.
The notion of providing a lightweight unprotected function (API) which requests pre-defined information (domain, email address, etc.) and returns an API key seemed like the most straight forward approach.
Interestingly, the bulk of talk about solutions was to provide a tiered approach for developers. Where if you have not been provisioned the user experience has more disclaimers and the number of calls to the API could be throttled until the developer “claims” the application. Perhaps this could be done by emailing the developer an “upsell” and they go to a web site to claim their application, or prove ownership of the domain.
Chris Messina had a really interesting point of view: instead of locking down the system, you have liberal access and when some type of abuse occurs the system could be self healing. e.g. an app deletes all of a user’s data, the user can log in and click rollback.
Aside from the technical work of “how do API keys get provisioned” the overall business issue of machine readable terms of services is a big complex problem. The position I asserted is this work should be driven by the DataPortability working group and some other people mentioned www.sciencecommons.org and www.opendefinition.org.
The outcomes/moving forward
For the 3 problem spaces the following plans set:
- 4th parties and widgets
- Setup and email thread with Facebook / Google and Plaxo to diff on this more
- Monitor Facebook’s progress as they are close to having a solution and provide feedback
- Enumerate all of the use cases and post to a wiki/blog
- Unattended registration with services
- Plaxo will drive this with Google (Eric Sachs) as the main requirement is coming from Portable Contacts.
- Enumerate all of the use cases and post to a wiki/blog
- Data rights
- The Data Portability group should keep on working on this.