Concepts

Authentication Providers & API Identities

When building an API documentation portal, you often need to provide a way for users to authenticate their API requests. This typically involves managing API keys and different authentication identities. However, implementing a secure and user-friendly system for API key management can be complex and time-consuming. Dev Portal provides a powerful solution to this problem through its API Keys and Identities system.

Authentication Providers and API Identities

Before diving into API Identities, it's important to understand that Dev Portal separates user authentication from API authentication. Authentication providers handle how users sign in to your documentation portal, while API Identities manage how these users interact with your APIs.

Authentication providers (like Auth0 or custom JWT) handle:

• User authentication for the documentation portal
• Session management
• User authorization and access control

This separation allows you to:

• Use different authentication methods for your portal and APIs
• Manage API access independently of user authentication
• Support multiple API authentication schemes simultaneously

Learn more about authentication providers

Understanding API Identities

API Identities in Dev Portal represent different authentication contexts that can be used to make API requests. These could be different environments (production, staging), different authentication methods (API key, JWT), or different service accounts.

The API Identity Interface

Code
 
interface ApiIdentity {
  id: string;
  label: string;
  authorizeRequest: (request: Request) => Promise<Request> | Request;
}

interface ApiIdentityPlugin {
  getIdentities: () => Promise<ApiIdentity[]> | ApiIdentity[];
}

Each API Identity consists of:

• id: A unique identifier for the identity
• label: A human-readable name shown in the UI
• authorizeRequest: A function that modifies requests to include the necessary authentication

Implementing API Identities

In this example, we'll use Auth0 as our authentication provider and implement an API Identity for a demo API.

To add API Identities to your Dev Portal configuration, you need to implement the ApiIdentityPlugin interface. Here's an example:

Code
 
import { createApiIdentityPlugin } from "zudoku/plugins";

export default {
  authentication: {
    type: "auth0",
    domain: "my-domain.auth0.com",
    clientId: "my-client-id",
  },
  plugins: [
    createApiIdentityPlugin({
      getIdentities: async (context) => [
        {
          id: "api-key-one",
          label: "My API Key",
          authorizeRequest: (request) => {
            // We get the access token from the
            // authentication provider (Auth0) and add it to the request headers
            const token = context.authentication?.getAccessToken();
            if (token) {
              request.headers.set("Authorization", `Bearer ${token}`);
            }
            return request;
          },
        },
      ],
    }),
  ],
};

When implemented, this identity will appear in the Dev Portal playground.