As your SaaS grows, your customers may want to connect your product with the rest of their tools, whether that's running scheduled jobs, syncing data, triggering workflows, or building private internal tools. These integrations all require the same foundational capability: A secure, reliable way to programmatically access your API.
API keys remain the simplest and most familiar way for customers to integrate with SaaS products. From a customer's perspective, API Keys should be easy to manage and use. But implementing API Keys correctly in a multi-tenant application takes real work:
Most teams eventually take on the work of building and maintaining their own approach to key management, which often turns into a complex, error-prone, and time-consuming effort.
Clerk removes that entire burden.
With Clerk API Keys, you can securely expose your application's functionality through an API for individual users or entire organizations, without having to build the underlying infrastructure yourself. In this guide, we'll introduce you to Clerk's new API Keys feature and show you how to integrate it into your SaaS product.
To make this tutorial practical and easy to apply, we'll be working with the AgentOps demo app — an open-source, multi-tenant Next.js application that showcases how to integrate Clerk's new API Keys system into a real SaaS product.
This demo includes a simple "Agents" concept (AI assistants) and uses organization-scoped API Keys to ensure that only authorized members of organizations can access resources.
The app features:
<APIKeys/> componentYou'll need the following before you get started:
If you want to follow along, clone the API Keys Demo repository on GitHub and navigate to the directory:
Then, run the following commands to install the dependencies and start the development server:
To follow along with the demo project, you'll need to enable a few features in your app instance. But before turning on API Key support, you'll need to decide how keys should be scoped.
Clerk supports two types of keys:
This tutorial will focus on Organization API Keys. Before you can use API Keys, you'll need to enable Organizations first.
To get started, open your app instance in the Clerk dashboard and navigate to Organizations > Settings from the sidebar on the left. Toggle Enable organizations on if the feature is not already enabled. From here, make sure personal accounts are disabled.
Next, switch to the Roles & Permissions tab and grant the following system permissions to your test user:
org:sys_api_keys:readorg:sys_api_keys:manageThese permissions determine who can view, generate, and revoke API Keys within your organization. In the following sections, you'll integrate API Keys into your application and start protecting your backend routes using Clerk's token verification layer.
Finally, navigate to Configure > Developer > API Keys. Toggle the Organization API keys option to enable it and click Save. Make sure to leave the User API keys option disabled.
Once API Keys are enabled in your Clerk instance, the next step is to expose a place in your product where your users can view, create, and manage their own API Keys. In our AgentOps example, this component is integrated directly into the existing shadcn dashboard layout.
<OrganizationProfile/> componentIf your application already includes an <OrganizationProfile/> or <OrganizationSwitcher/> component, Clerk automatically adds an API Keys tab when the minimum permissions (org:sys_api_keys:read) are present. These permissions are not set by default, so you'll need to apply them to both admin and member roles in the Clerk dashboard.
In the demo app, you can try this by:
<OrganizationSwitcher/> in the dashboard headerFrom here, organization members with org:sys_api_keys:read can view all active Organization API Keys, and members with org:sys_api_keys:manage can create new keys with one click, revoke any key immediately, and copy keys securely for external usage.
Here's the header layout used in the demo:
When you click Manage Organization in the <OrganizationSwitcher/> component, you'll see the API Keys tab appear automatically if permissions are configured correctly.
<APIKeys/> componentIf you'd prefer to have more control over where API Keys appear in your application, Clerk also provides a dedicated <APIKeys/> component that you can use.
Our demo app shows how to embed API Key management directly inside your own dashboard pages, which is useful if you want a dedicated “Developer Settings” or “Integrations” section.
Here's the example from the demo:
This version gives you full control over where API Keys appear in your dashboard while Clerk handles security and key management.
With key generation enabled, the next step is to allow your API to accept API Keys alongside normal user session tokens. Clerk makes this extremely simple with a single configuration change.
In server-side functions and API routes, Clerk's auth() helper can accept more than one token type.
In our demo app, we've configured our /api/agents/route.ts file to accept both session tokens and API Keys.
Below is a simplified example:
This line tells Clerk to accept:
Clerk automatically extracts and verifies the token, determines the organization, and ensures the key has not been revoked.
Because Clerk includes orgId directly in the token, your backend logic becomes extremely straightforward:
orgId → rejectorgId does not match the requested resource → rejectThis ensures strong multi-tenant isolation and prevents customers from ever accessing resources outside their organization.
Now that API Keys are enabled and visible in your application’s dashboard, it’s time to test them against real API endpoints in the demo app. You can use cURL or tools like Insomnia or Postman to test your API Keys.
Go ahead and create an API Key on the /dashboard/settings/api-keys page using the <APIKeys/> component from the previous section.
With your key in hand, you can start making real requests.
Let's start by creating a new agent using the POST /api/agents endpoint. This endpoint requires a valid Organization API Key.
If successful, you'll see the newly created agent returned in the response.
Since every request is tied to your Organization ID, the new agent is automatically scoped to your organization.
Now, try to create an agent with an invalid API Key.
If the key is invalid (or revoked / expired), the request will be rejected with a 401 Unauthorized response.
You can test the same functionality from a logged-in user context by creating an agent on the /dashboard page.
Next, fetch all agents that belong to your organization.
You should get a response with an array containing the recently created agent:
Finally, delete an existing agent by using the DELETE /api/agents endpoint and sending its agentId in the request body:
Clerk validates the API Key, resolves the organization it belongs to, and ensures the deletion request only affects resources owned by that org.
You can test the same functionality from a logged-in user context by deleting an agent on the /dashboard page.
By this point, you've tested that:
Your platform can support external integrations and every API request passes through Clerk's verification. This mirrors how your real users will interact with your API.
Adding API Key support to a SaaS product is often a significant engineering effort, especially in a multi-tenant environment where every request must be scoped to the correct organization. Clerk removes that complexity by managing key creation, access controls, token validation, and providing ready-made UI components for your customers.
In just a few steps, you've put all the essential pieces in place:
Taken together, these steps give you a fast, secure foundation for customer-facing integrations—one that you can adapt to your product's needs. With this setup in place, your customers can connect your SaaS to the rest of their workflow with ease.
To explore the complete setup for this guide, check out the AgentOps API Keys Demo. For more advanced use cases, check out the examples in this repository.
Other resources:
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。