Optimize Time-To-First-Call with API key auth

by Abdallah Abedraba

We’ve talked before about how good API providers deeply care about metrics like the time-to-first-call (TTFC). Those vital moments before discovering your API and hitting Enter on their first call are core to your API’s entire developer experience and how quickly you can get them to experience what you’ve created—fast—and send them along to start building.

JWTs have clear security implications, like a lack of revocability and opaqueness, but for now, we’re focused on how they impede your TTFC metric in potentially unforeseen ways you can’t make up for with other initiatives, like forkable templates or a developer sandbox.

JWT and the impact on TTFC#

If you’re using JSON Web Tokens (JWTs) for API authentication, you have a roadblock between your new developer and their first call: a third-party identity provider like OAuth, which validates clients on your behalf. The way a developer must interact with this identity provider for authentication creates friction through the additional steps required they can call your API, which harms your TTFC.

You’re also maintaining a method of supplying each developer and their applications with Client Id and Client Secret, which are like a username and password, taking valuable engineering time away from working on other DX-specific efforts.

Here is the typical end-user flow of API authentication using JWT, OAuth:

1. The developer explores your website and/or documentation.

2. They create an account with the explicit goal of calling your API, in an M2M situation, to enable their application.

3. They navigate to an authentication portion of your application/dashboard and request a Client Id and Client Secret.

4. They use their new Client Id and Client Secret to make a request to OAuth, which operates as your third-party identity provider. You can help them make this request in a few ways:

   a. An example curl request, to which they can add their credentials.

   b. Sample code for them to implement within their application alongside its API calls.

5. In response, the developer receives an access token from OAuth, either as a response to their curl request or their application.

6. They navigate to your API documentation, which contains curl and/or code examples for calling your API.

7. They copy-and-paste an example and replace an ACCESS_TOKEN variable with their access token, to properly set the HTTP request’s Bearer token.

8. They hit Enter to make their first call.

API key authentication for a smoother TTFC#

Like JWTs, key-based authentication for your API presents an important technical question: Will you build your own API key auth and infrastructure, or will you abstract that logic, storage, and global presence to a third party?

An API gateway provider can not only store API keys for you utilizing best practices for encrypted secure storage, checksum validation, secret scanning, and more—in a way that streamlines the developer experience instead of operating as a roadblock. Let’s look at both scenarios and how API keys impact the TTFC.

With ‘vanilla’ API key authentication#

The first two steps are the same as our JWT example, but then the developer experience changes:

3. The developer navigates to an API key section of your application/dashboard, where they generate a new API key.
4. They navigate to your API documentation, which contains curl and/or code examples for calling your API.
5. They copy-and-paste an example and replace an API_KEY variable with their API key.
6. They hit Enter to make the first call.

With Zuplo’s API gateway and preconfigured API keys#

Again, with identical first steps, the TTFC gets even shorter:

2. Upon completing signup, your application redirects them to your Zuplo-powered developer portal, logs them in, and automatically generates their first API key.
3. They copy-and-paste an example, which already contains their new API key.
4. They hit Enter to make their first call.

Visualizing the impact on TTFC#

What’s next: Carve down your TTFC#

If you’re using JWT with either an internal implementation or an identity provider like OAuth, you’re creating unnecessary friction between your new developer and their first API call. Same goes for a “vanilla” implementation API key authentication, but, as you can see above, to a far lesser extent.

But developer experience is about far more than the first few moments of a developer using your API—JWTs struggle in more complex scenarios as well.

• Specific access tokens are not revocable, so you must roll the developer’s Client Id and Client Secret, breaking all their JWTs, during a security breach incident.
• You can’t control permissions for multiple access tokens from the same client because your identity provider manages them.
• The developer is responsible for requesting a new access token using their Client Id and Client Secret every time their JWT expires.

A migration from JWTs to API key authentication will certainly whittle down your TTFC (and it’s quite simple with Zuplo’s API key management tools and open source React component), but it’s not the only path for improving the developer experience:

• Provide rich, complete, and up-to-date documentation, like the developer portal available with every API you serve through Zuplo.
• Format API requests in a way that is quickly executable and familiar to many developers.
• Demonstrate use cases and examples, or provide a sandbox for making test calls to familiarize users with your endpoints and specs before asking them to jump in.
• Organize your API information and examples to help developers self-select based on their use case, experience level, or industry concepts.

Zuplo’s serverless API Gateway also helps you in other ways, like API documentation with built-in tools for developers to generate and roll their API keys on their terms, and a global edge presence and caching for 50ms response times no matter where your API is hosted.

Zuplo integrates with your existing APIs and tooling with rich key management and much more—try it now for free, then let us know on Discord about your time-to-first-API-gateway.