Machine-to-Machine API Signup
Is it possible to make API signups fully automated?
What's the initial thing you need to do before you can use an API for the first time? If the API is not publicly available for anyone to use, signing up is mandatory. There have been many improvements in the way signups work. However, it's still not possible to do it without a human. Or, is it?
This article is brought to you with the help of our supporter: Speakeasy.
Speakeasy provides you with the tools to craft truly developer-friendly integration experiences for your APIs: idiomatic, strongly typed, lightweight & customizable SDKs in 8+ languages, Terraform providers & always-in-sync docs. Increase API user adoption with friction-free integrations.
Signing up is something you have to do before being able to use any Web product, including an API. The signup activity varies from service to service but follows a common pattern. A part of any signup process has to do with authentication. Another part obtains identity and sometimes payment-related information.
The first part of any signup—the one that deals with authentication—has evolved substantially. To the point where many services eliminate the need to type a username and choose a password. Instead, they use third-party authentication providers such as Google. "Signing up with Google," for example, lets you bypass not just the authentication but also to some extent the sharing of your identity.
However, you still have to go through the process manually. When it comes to payment-related information things get even worse. Your options are to either enter some valid form of payment, like a credit card or rely on a third party. Some services rely on providers such as Google, Apple, or Stripe, to obtain your payment credentials. That alleviates the burden of having to manually enter the required information. But, again, it still requires a manual confirmation from a human.
After you have successfully signed up by following the identity and payment-related steps, you can then access authentication information to finally start using the API. There are different authentication mechanisms such as the more traditional API key, and an OAuth client credential you can use to authorize end users. What's important is that from here on, the integration you're building with the API can run autonomously, without your intervention.
So, why do you need to manually sign up to use an API? Why haven't API providers evolved to a point where the signup process doesn't require human intervention? Let's focus on the identity part of the signup process. It looks like it's the easiest part to understand and the one we can address with the existing technology.
It looks to me that the reason identity needs to be manually verified is to make sure there's a person behind the API integration. Or, at least, there's someone accountable for the integration. However, in most cases, you don't need to ensure a human is actually performing the API requests. In the end, in most situations, the connection with the API will be handled by another machine.
What if there was a way to perform an automated registration where one machine could execute the signup process without the intervention of a person? Fortunately, it exists. And it's described in RFC 7591. It's called "OAuth 2.0 Dynamic Client Registration Protocol" and it defines mechanisms for dynamically registering API consumers using OAuth. These mechanisms let you completely bypass what you'd have to do manually during a normal signup process.
The dynamic client registration protocol works by allowing potential clients to register themselves. The registration happens on a specific reserved endpoint, e.g., /register that accepts a payload with enough information to identify the client. After a potential client is registered it can then authorize end users using well-known OAuth flows. What's interesting is that the RFC describes a way to register without the need of previously establish an identity with the API. In other words, potential API clients can register themselves in a fully automated fashion.
Authorization servers that support open registration allow
registrations to be made with no initial access token. This allows all client software to register with the authorization server.
RFC 7591 was published in 2015 and evolved into the "OpenID Connect Dynamic Client Registration." Its latest version is from December 2023 and it fully defines the automated registration mechanism. According to the specification, the only required information is related to the redirect URIs that will be used by the client to authorize end users. However, it defines interesting information that a potential client can share during its registration:
Contacts: A list of e-mail addresses of the people responsible for the client software.
Client name: The name of the application that is displayed to end users.
Logo: A URL of a logo that can be presented to end users.
Client URL: A Web page that can be presented to end users when they want more information about the application.
Terms-of-service URL: A Web page that includes the terms-of-service that end users might want to read before using the software.
By supporting this information both API clients and providers can offer a better experience to end users. All without having to go through a manual signup and configuration process. Imagine you're building software that integrates with multiple APIs. You'd only have to define these details once and then the dynamic registration would provision your client on all the APIs you'd want to use.
In the end, this mechanism improves the interaction between API clients and servers. By eliminating the need to manually sign up every time you want to use an API, you'd have a much better Developer Experience. Finally, by being able to provide client-related information you'd offer an end-user experience comparable to what you can offer today using a manual signup process.