stack/docs/templates/concepts/api-keys.mdx

---
title: API Keys
description: 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. 

<Mermaid chart={`
sequenceDiagram
    participant User as User/Client
    participant Server as Your Application Server
    participant Stack as Stack Auth Service
    
    User->>+Server: API request with API key
    Server->>+Stack: Validate API key
    Stack-->>-Server: Return authenticated User object
    Server->>Server: Process request
    Server-->>-User: Response with data
`} />

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.

<Tabs defaultValue="client">
  <TabsList>
    <TabsTrigger value="client">Client</TabsTrigger>
    <TabsTrigger value="server">Server</TabsTrigger>
  </TabsList>
  <TabsContent value="client">
    ```typescript
    const user = await stackApp.getUser();
    
    const apiKey = await user.createApiKey({
      description: "My client application",
      expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90 days
      isPublic: false,
    });
    ```
  </TabsContent>
  <TabsContent value="server">
    ```typescript
    const user = await stackServerApp.getServerUserById("user-id-here");
    
    const apiKey = await user.createApiKey({
      description: "Admin-provisioned API key",
      expiresAt: new Date(Date.now() + (30 * 24 * 60 * 60 * 1000)), // 30 days
      isPublic: false,
    });
    ```
  </TabsContent>
</Tabs>

### Team API keys

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

<Tabs defaultValue="client">
  <TabsList>
    <TabsTrigger value="client">Client</TabsTrigger>
    <TabsTrigger value="server">Server</TabsTrigger>
  </TabsList>
  <TabsContent value="client">
    ```typescript
    const user = await stackApp.getUser();
    const team = await user.getTeam("team-id-here");
    
    const teamApiKey = await team.createApiKey({
      description: "Team integration service",
      expiresAt: new Date(Date.now() + (60 * 24 * 60 * 60 * 1000)), // 60 days
      isPublic: false,
    });
    ```
  </TabsContent>
  <TabsContent value="server">
    ```typescript
    const team = await stackServerApp.getTeam("team-id-here");
    
    const teamApiKey = await team.createApiKey({
      description: "Admin-provisioned team API key",
      expiresAt: new Date(Date.now() + (30 * 24 * 60 * 60 * 1000)), // 30 days
      isPublic: false,
    });
    ```
  </TabsContent>
</Tabs>

## 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

<Tabs defaultValue="client">
  <TabsList>
    <TabsTrigger value="client">Client</TabsTrigger>
    <TabsTrigger value="server">Server</TabsTrigger>
  </TabsList>
  <TabsContent value="client">
    ```typescript
    const apiKey = await user.createApiKey({
      description: "Development environment key",
      expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90 days from now
      isPublic: false,
    });
    ```
  </TabsContent>
  <TabsContent value="server">
    ```typescript
    const userId = "user-id-here";
    const user = await stackServerApp.getServerUserById(userId);
    
    const apiKey = await user.createApiKey({
      description: "API key created by server",
      expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90 days
      isPublic: false,
    });
    ```
  </TabsContent>
</Tabs>

### Creating Team API Keys

<Tabs defaultValue="client">
  <TabsList>
    <TabsTrigger value="client">Client</TabsTrigger>
    <TabsTrigger value="server">Server</TabsTrigger>
  </TabsList>
  <TabsContent value="client">
    ```typescript
    const team = await user.getTeam("team-id-here");
    
    const teamApiKey = await team.createApiKey({
      description: "Team service integration",
      expiresAt: new Date(Date.now() + (60 * 24 * 60 * 60 * 1000)), // 60 days
      isPublic: false,
    });
    ```
  </TabsContent>
  <TabsContent value="server">
    ```typescript
    const team = await stackServerApp.getTeam("team-id-here");
    
    const teamApiKey = await team.createApiKey({
      description: "Server-created team API key",
      expiresAt: new Date(Date.now() + (60 * 24 * 60 * 60 * 1000)), // 60 days
      isPublic: false,
    });
    ```
  </TabsContent>
</Tabs>

### Listing API Keys

<Tabs defaultValue="client">
  <TabsList>
    <TabsTrigger value="client">Client</TabsTrigger>
    <TabsTrigger value="server">Server</TabsTrigger>
  </TabsList>
  <TabsContent value="client">
    ```typescript
    // List user's API keys
    const userApiKeys = await user.listApiKeys();
    
    // List a team's API keys
    const team = await user.getTeam("team-id-here");
    const teamApiKeys = await team.listApiKeys();
    
    // Using hooks in React components
    const apiKeys = user.useApiKeys();
    const teamApiKeys = team.useApiKeys();
    ```
  </TabsContent>
  <TabsContent value="server">
    ```typescript
    // List a specific user's API keys
    const user = await stackServerApp.getServerUserById("user-id-here");
    const userApiKeys = await user.listApiKeys();
    
    // List a team's API keys
    const team = await stackServerApp.getTeam("team-id-here");
    const teamApiKeys = await team.listApiKeys();
    ```
  </TabsContent>
</Tabs>

### Revoking API Keys

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

<Tabs defaultValue="client">
  <TabsList>
    <TabsTrigger value="client">Client</TabsTrigger>
    <TabsTrigger value="server">Server</TabsTrigger>
  </TabsList>
  <TabsContent value="client">
    ```typescript
    const apiKeys = await user.listApiKeys();
    const apiKeyToRevoke = apiKeys.find(key => key.id === "api-key-id-here");
    
    if (apiKeyToRevoke) {
      await apiKeyToRevoke.revoke();
    }
    ```
  </TabsContent>
  <TabsContent value="server">
    ```typescript
    const user = await stackServerApp.getServerUserById("user-id-here");
    const apiKeys = await user.listApiKeys();
    
    const apiKeyToRevoke = apiKeys.find(key => key.id === "api-key-id-here");
    
    if (apiKeyToRevoke) {
      await apiKeyToRevoke.revoke();
    }
    ```
  </TabsContent>
</Tabs>

### Checking API Key Validity

You can check if an API key is still valid:

```typescript
const apiKeys = await user.listApiKeys();
const apiKey = apiKeys.find(key => key.id === "api-key-id-here");

if (apiKey && apiKey.isValid()) {
  // API key is valid
} else {
  // API key is invalid (expired or revoked)
  const reason = apiKey ? apiKey.whyInvalid() : "not found";
  console.log(`API key is invalid: ${reason}`);
}
```