From 0c2682afe215135e2ea0d69940b0b97597c1ae4f Mon Sep 17 00:00:00 2001 From: Madison Kennedy Date: Tue, 22 Apr 2025 12:08:04 +0000 Subject: [PATCH] Concepts page for api keys --- .../docs/pages-template/concepts/api-keys.mdx | 206 ++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 docs/fern/docs/pages-template/concepts/api-keys.mdx diff --git a/docs/fern/docs/pages-template/concepts/api-keys.mdx b/docs/fern/docs/pages-template/concepts/api-keys.mdx new file mode 100644 index 000000000..8e97d9b9e --- /dev/null +++ b/docs/fern/docs/pages-template/concepts/api-keys.mdx @@ -0,0 +1,206 @@ +--- +slug: concepts/api-keys +subtitle: 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 users to interact with their own data without requiring username/password authentication for each request. +yourou can offer both user-specific and team-based API keys that can be created, managed, and revoked as needed. + +## 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 to access their own data. These keys can be created by users themselves or by administrators on behalf of users. + + + + ```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, + }); + ``` + + + ```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, + }); + ``` + + + +### Team API keys + +Team API keys are associated with teams and provide access to team resources. These are useful for shared services or applications that need to access team data. + + + + ```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, + }); + ``` + + + ```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, + }); + ``` + + + +## 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 + + + + ```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, + }); + ``` + + + ```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, + }); + ``` + + + +### Creating Team API Keys + + + + ```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, + }); + ``` + + + ```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, + }); + ``` + + + +### Listing API Keys + + + + ```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(); + ``` + + + ```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(); + ``` + + + +### Revoking API Keys + +API keys can be revoked when they are no longer needed or if they have been compromised. + + + + ```typescript + const apiKeys = await user.listApiKeys(); + const apiKeyToRevoke = apiKeys.find(key => key.id === "api-key-id-here"); + + if (apiKeyToRevoke) { + await apiKeyToRevoke.revoke(); + } + ``` + + + ```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(); + } + ``` + + + +### 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}`); +} +```