Skip to main content

Documentation Index

Fetch the complete documentation index at: https://stackauth-e0affa27-apps-support.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The API Keys app enables your users to generate and manage API keys for programmatic access to your backend services. API keys provide a secure way to authenticate requests, allowing developers to associate API calls with specific users or teams. Stack Auth provides prebuilt UI components for users and teams to manage their own API keys.

​
Overview

API keys allow your users to access your backend services programmatically without interactive authentication. The flow works as follows: a user or client sends an API request with an API key to your application server. Your server validates the API key with Stack Auth, which returns an authenticated User object. Your server then processes the request and returns the response. Stack Auth provides two types of API keys:

​
User API keys

User API keys are associated with individual users and allow them to authenticate with your API.
app/components/create-api-key.tsx
"use client";
import { useUser } from "@stackframe/stack";

export default function CreateApiKey() {
  const user = useUser({ or: 'redirect' });

  const handleCreateKey = async () => {
    const apiKey = await user.createApiKey({
      description: "My client application",
      expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90 days
    });

    console.log("API Key created:", apiKey.value);
  };

  return <button onClick={handleCreateKey}>Create API Key</button>;
}

​
Team API keys

Team API keys are associated with teams and can be used to provide access to team resources over your API.
app/components/create-team-api-key.tsx
"use client";
import { useUser } from "@stackframe/stack";

export default function CreateTeamApiKey({ teamId }: { teamId: string }) {
  const user = useUser({ or: 'redirect' });
  const team = user.useTeam(teamId);

  const handleCreateKey = async () => {
    if (!team) return;

    const teamApiKey = await team.createApiKey({
      description: "Team integration service",
      expiresAt: new Date(Date.now() + (60 * 24 * 60 * 60 * 1000)), // 60 days
    });

    console.log("Team API Key created:", teamApiKey.value);
  };

  return <button onClick={handleCreateKey}>Create Team API Key</button>;
}

​
Enabling the API Keys App

To use API keys in your application, you need to enable the API Keys app in your Stack Auth dashboard:
  1. Navigate to your Stack Auth dashboard
  2. Go to the Apps section
  3. Find and click on API Keys in the app store
  4. Click the Enable button
Once enabled, you can configure User API Keys and Team API Keys in the app settings. The app will provide your users with a prebuilt UI to manage their own API keys.

​
Prebuilt UI Components

Stack Auth provides prebuilt UI components that allow your users to manage their own API keys without any additional code:

​
User API Keys UI

For frameworks that support React components, the <AccountSettings> component includes an API Keys tab where users can:
  • View all their active API keys
  • Create new API keys with custom descriptions and expiration dates
  • Revoke existing API keys
  • See when each key was created and when it expires.
app/src/account-page.tsx
import { AccountSettings } from '@stackframe/stack';

export default function MyAccountPage() {
  return (
    <AccountSettings
      fullPage={true}
    />
  );
}

​
Team API Keys UI

For team API keys, the team settings page automatically includes an API Keys section when:
  • The API Keys app is enabled
  • allowTeamApiKeys is configured in your project settings
  • The user has the $manage_api_keys permission for the team
Users with appropriate permissions can manage team API keys directly from the team settings interface.

​
Working with API Keys

​
Creating User API Keys

app/components/create-api-key.tsx
"use client";
import { useUser } from "@stackframe/stack";

export default function CreateApiKey() {
  const user = useUser({ or: 'redirect' });

  const handleCreateKey = async () => {
    const apiKey = await user.createApiKey({
      description: "My client application",
      expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90 days
    });

    console.log("API Key created:", apiKey.value);
  };

  return <button onClick={handleCreateKey}>Create API Key</button>;
}

​
Creating Team API Keys

app/components/create-team-api-key.tsx
"use client";
import { useUser } from "@stackframe/stack";

export default function CreateTeamApiKey({ teamId }: { teamId: string }) {
  const user = useUser({ or: 'redirect' });
  const team = user.useTeam(teamId);

  const handleCreateKey = async () => {
    if (!team) return;

    const teamApiKey = await team.createApiKey({
      description: "Team integration service",
      expiresAt: new Date(Date.now() + (60 * 24 * 60 * 60 * 1000)), // 60 days
    });

    console.log("Team API Key created:", teamApiKey.value);
  };

  return <button onClick={handleCreateKey}>Create Team API Key</button>;
}

​
Listing API Keys

app/components/api-keys-list.tsx
"use client";
import { useUser } from "@stackframe/stack";

export default function ApiKeysList() {
  const user = useUser({ or: 'redirect' });
  const apiKeys = user.useApiKeys();

  return (
    <div>
      <h2>Your API Keys</h2>
      {apiKeys.map(key => (
        <div key={key.id}>
          <p>{key.description}</p>
          <p>Last 4 digits: {key.value.lastFour}</p>
          <p>Created: {key.createdAt.toLocaleDateString()}</p>
        </div>
      ))}
    </div>
  );
}

​
Revoking API Keys

API keys can be revoked when they are no longer needed or if they have been compromised.
app/components/revoke-api-key.tsx
"use client";
import { useUser } from "@stackframe/stack";

export default function RevokeApiKey({ apiKeyId }: { apiKeyId: string }) {
  const user = useUser({ or: 'redirect' });
  const apiKeys = user.useApiKeys();

  const handleRevoke = async () => {
    const apiKeyToRevoke = apiKeys.find(key => key.id === apiKeyId);

    if (apiKeyToRevoke) {
      await apiKeyToRevoke.revoke();
      console.log("API Key revoked");
    }
  };

  return <button onClick={handleRevoke}>Revoke API Key</button>;
}

​
Checking API Key Validity

You can check if an API key is still valid:
app/components/check-api-key.tsx
"use client";
import { useUser } from "@stackframe/stack";

export default function CheckApiKeyValidity({ apiKeyId }: { apiKeyId: string }) {
  const user = useUser({ or: 'redirect' });
  const apiKeys = user.useApiKeys();

  const apiKey = apiKeys.find(key => key.id === apiKeyId);

  if (!apiKey) {
    return <div>API key not found</div>;
  }

  if (apiKey.isValid()) {
    return <div>API key is valid</div>;
  }

  const reason = apiKey.whyInvalid();
  return <div>API key is invalid: {reason}</div>;
}