Concepts

API Keys

Create and manage API keys for users and teams

API keys provide a secure way for your users to authenticate with your application’s backend. They enable programmatic access to your API services, allowing developers to associate requests with specific users or teams. Stack Auth provides prebuilt UI components for the users and teams to manage their own API keys.

Overview

API keys allow your users to access your backend services programmatically.

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.

1const user = await stackApp.getUser();
2
3const apiKey = await user.createApiKey({
4  description: "My client application",
5  expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90 days
6  isPublic: false,
7});

Team API keys

Team API keys are associated with teams and can be used to provide access to team resources over your API.

1const user = await stackApp.getUser();
2const team = await user.getTeam("team-id-here");
3
4const teamApiKey = await team.createApiKey({
5  description: "Team integration service",
6  expiresAt: new Date(Date.now() + (60 * 24 * 60 * 60 * 1000)), // 60 days
7  isPublic: false,
8});

Setting Up API Keys in Stack Auth

To use API keys in your application, you need to enable them in your project settings. Navigate to the Stack Auth dashboard, select your project, and enable User API Keys and/or Team API Keys in the project settings.

Working with API Keys

Creating User API Keys

1const apiKey = await user.createApiKey({
2  description: "Development environment key",
3  expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90 days from now
4  isPublic: false,
5});

Creating Team API Keys

1const team = await user.getTeam("team-id-here");
2
3const teamApiKey = await team.createApiKey({
4  description: "Team service integration",
5  expiresAt: new Date(Date.now() + (60 * 24 * 60 * 60 * 1000)), // 60 days
6  isPublic: false,
7});

Listing API Keys

1// List user's API keys
2const userApiKeys = await user.listApiKeys();
3
4// List a team's API keys
5const team = await user.getTeam("team-id-here");
6const teamApiKeys = await team.listApiKeys();
7
8// Using hooks in React components
9const apiKeys = user.useApiKeys();
10const teamApiKeys = team.useApiKeys();

Revoking API Keys

API keys can be revoked when they are no longer needed or if they have been compromised.

1const apiKeys = await user.listApiKeys();
2const apiKeyToRevoke = apiKeys.find(key => key.id === "api-key-id-here");
3
4if (apiKeyToRevoke) {
5  await apiKeyToRevoke.revoke();
6}

Checking API Key Validity

You can check if an API key is still valid:

1const apiKeys = await user.listApiKeys();
2const apiKey = apiKeys.find(key => key.id === "api-key-id-here");
3
4if (apiKey && apiKey.isValid()) {
5  // API key is valid
6} else {
7  // API key is invalid (expired or revoked)
8  const reason = apiKey ? apiKey.whyInvalid() : "not found";
9  console.log(`API key is invalid: ${reason}`);
10}