API Keys

API keys provide a secure way for your application’s users to authenticate with your API. With the API Keys Widget, your customers can create and revoke API keys with a simple component. API keys can be scoped to an organization or to an individual user in an organization. The WorkOS API and SDKs provide functions for your API code to validate keys.

API keys are one of two ways WorkOS enables you to issue credentials to your customers that they use to programmatically access your application. The other is M2M applications. The API Keys vs M2M Applications guide can help you decide which is best for your use case.

Before your users can manage API keys, you need to configure your WorkOS environment.

To enable organization API key management for your users, ensure at least one role includes the widgets:api-keys:manage permission. This permission allows users to access the API Keys Widget and manage keys within their organization.

To enable user API key management, assign at least one of the following permissions:

• widgets:user-api-keys:manage-self – Allows users to create, view, and revoke their own API keys.
• widgets:user-api-keys:manage-all – Allows users to view and revoke API keys owned by any other user in the organization.

You can assign permissions to roles in the WorkOS Dashboard under Authorization.

You can control which permissions your users can assign to API keys by configuring API key permissions in your environment.

For example, you might create permissions like:

• posts:read – Read access to posts
• posts:write – Write access to posts
• users:read – Read access to user data

By configuring only posts:read and posts:write as available API key permissions, your users can create API keys with granular access controls, such as read-only keys that only have the posts:read permission.

Organization API keys and user API keys each have their own set of assignable permissions. You can configure API key permissions in the WorkOS Dashboard under Authorization > Configuration > API key permissions.

The easiest way to enable API key management for your users is through the API Keys Widget. This widget provides a complete interface for creating, viewing, and revoking API keys.

Use the default scope="organization" mode when users should manage API keys owned by their organization. Use scope="user" when users should manage API keys owned by individual users.

The widget allows your users to:

• Create new API keys with custom names
• Select specific permissions for each key
• View existing API keys (with obfuscated values for security)
• Revoke API keys when they’re no longer needed

The widget interacts with the WorkOS API and renders the user interface in your app, so your customers get full control over their API keys in just a few lines of code.

You can also manage organization API keys programmatically using the WorkOS API. This is useful for building custom organization API key management interfaces or automating key lifecycle operations.

• Create an API key for an organization
• List API keys for an organization
• Delete an API key

Once API keys have been created, your application needs to validate these keys when they’re used to authenticate API requests. When an API request includes an API key (typically in the Authorization header), your application should validate it with WorkOS to ensure it’s legitimate and retrieve the associated permissions.

The validate API key endpoint returns the complete API key object, including:

• The owner of the key, which can be an organization or a user
• The permissions assigned to the key
• Usage metadata like creation and last-used timestamps

This information allows your application to not only authenticate the request but also authorize it based on the specific permissions granted to that API key. For user API keys, the owner metadata identifies the user and the organization context for the key.

import { NextResponse } from 'next/server';
import { validateApiKey } from '@workos-inc/authkit-nextjs';

export async function GET() {
  const { apiKey } = await validateApiKey();

  if (!apiKey) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  return NextResponse.json({ success: true });
}

You can view and revoke your customers’ organization API keys through the WorkOS Dashboard or via the API:

1. Navigate to the Organizations section in your WorkOS Dashboard
2. Click on the organization you want to view
3. Select the API Keys tab

From this view, you can see all API keys created by the organization, including their names, permissions, creation dates, and last usage information. This provides valuable visibility into how your customers are using organization API keys.

User API keys are created and managed through the API Keys Widget with scope="user".

API key lifecycle changes are tracked via the api_key.created and api_key.revoked events. You can view these events in the events page or listen for them in your application via the events API.