Add Python SDK tab to docs

N2D4 · N2D4 · commit bb8e28a275cd · 2025-03-04T18:24:32.000-08:00
diff --git a/apps/e2e/tests/general/setup-wizard.test.ts b/apps/e2e/tests/general/setup-wizard.test.ts
@@ -10,5 +10,5 @@ describe("Setup wizard", () => {
       });
     });
     expect(error, `Expected no error to be thrown!\n\n\n\nstdout: ${stdout}\n\n\n\nstderr: ${stderr}`).toBeNull();
-  }, 120_000);
+  }, 240_000);
 });
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,6 +1,8 @@
 fern/js.yml
 fern/next.yml
 fern/react.yml
+fern/python.yml
 fern/docs/pages-js
 fern/docs/pages-next
 fern/docs/pages-react
+fern/docs/pages-python
diff --git a/docs/fern/docs-template.yml b/docs/fern/docs-template.yml
@@ -28,6 +28,7 @@ navigation:
         icon: fa-regular fa-circle-question
         path: ./docs/pages-{platform}/faq.mdx
       - section: Getting Started
+        platform: js-like
         contents:
           - page: Installation & Setup
             icon: fa-regular fa-download
@@ -46,7 +47,14 @@ navigation:
           - page: Going to Production
             icon: fa-regular fa-rocket
             path: ./docs/pages-{platform}/getting-started/production.mdx
+      - section: Getting Started
+        platform: python-like
+        contents:
+          - page: Setup
+            icon: fa-regular fa-download
+            path: ./docs/pages-{platform}/getting-started/setup.mdx
       - section: Concepts
+        platform: js-like
         contents:
           - page: The StackApp Object
             icon: fa-regular fa-folder-gear
@@ -103,6 +111,7 @@ navigation:
               - page: Password Reset
                 path: ./docs/pages-{platform}/customization/page-examples/password-reset.mdx
       - section: Others
+        platform: js-like
         contents:
           - page: Supabase Integration
             icon: fa-regular fa-bolt
@@ -158,6 +167,7 @@ navigation:
             icon: fa-solid fa-square-u
             path: ./docs/pages-{platform}/components/stack-theme.mdx
   - tab: sdk
+    platform: js-like
     layout:
       - page: SDK Overview
         icon: fa-regular fa-globe
diff --git a/docs/fern/docs.yml b/docs/fern/docs.yml
@@ -19,6 +19,9 @@ versions:
   - display-name: JavaScript SDK
     path: js.yml
     slug: js
+  - display-name: Python SDK
+    path: python.yml
+    slug: python
 
 navbar-links:
   - type: secondary
diff --git a/docs/fern/docs/pages-template/faq.mdx b/docs/fern/docs/pages-template/faq.mdx
@@ -6,19 +6,19 @@ subtitle: Frequently asked questions about Stack
 ## Languages & Frameworks
 <AccordionGroup>
   <Accordion title="What languages are supported?">
-    In the frontend, Stack supports TypeScript and JavaScript with Next.js. In the backend, Stack has a flexible [REST API](/rest-api) that can be used with any language or framework.
+    For frontends, Stack supports TypeScript and JavaScript. For backends, Stack has a flexible [REST API](/rest-api) that can be used with any language or framework.
   </Accordion>
   <Accordion title="Can I use Stack with other JavaScript frameworks, like Astro or Angular?">
-    While you can use any backend framework with Stack, the frontend is tightly integrated with Next.js. If you want to use a different frontend framework, you will have to build the integration ourselves with the client endpoints of our [REST API](/rest-api). Some members of our community have started projects to do this, so you may want to join [our Discord](https://discord.stack-auth.com) to coordinate with them.
+    Yes! You can use our vanilla JavaScript SDK, or, if the framework is React-based, our React SDK.
   </Accordion>
   <Accordion title="Can I use Stack with the Next.js pages router?">
-    Only the Next.js app router is currently supported. However, just like any other unsupported framework, you can use the client endpoints of our [REST API](/rest-api) to build your own integration.
+    Only the Next.js app router is currently officially supported, although some members of the community have successfully used the React or vanilla JavaScript SDKs with the pages router.
   </Accordion>
 </AccordionGroup>
 
 ## Product
 <AccordionGroup>
-  <Accordion title="How do you compare to <X>?">
+  <Accordion title="How do you compare to `<X>`?">
     Ask yourself about `<X>`:
 
     - Is `<X>` open-source?
diff --git a/docs/fern/docs/pages-template/getting-started/setup.mdx b/docs/fern/docs/pages-template/getting-started/setup.mdx
@@ -387,4 +387,78 @@ We recommend using our **setup wizard** for a seamless installation experience.
 
 Check out the [Users](./users.mdx) to learn how to retrieve and update user information, or [Example pages](./example-pages.mdx) to see how to build your sign-in/up pages.
 
+
+{/* ELSE_IF_PLATFORM python */}
+
+<Info>
+Welcome to the Python setup guide. If you're looking for guides for other frameworks, check out the [Next.js SDK Setup](../../pages-next/getting-started/setup.mdx), [React SDK Setup](../../pages-react/getting-started/setup.mdx), or the [JavaScript SDK Setup](../../pages-js/getting-started/setup.mdx).
+</Info>
+
+Our recommended way to use Stack Auth with Python is with the [REST API](../rest-api/overview.mdx). It provides a fully documented way to interact with Stack Auth from any Python framework, including Flask, FastAPI, and Django.
+
+For the purpose of this guide, we will use the `requests` library to make HTTP requests to the Stack Auth API. If you haven't already, you can install it in your environment with `pip install requests`.
+
+<Steps>
+  ### Create API keys
+
+  First, create an account on [the Stack Auth dashboard](https://app.stack-auth.com/projects), and copy your project ID, publishable client key, and secret server key into a safe place (eg. environment variables).
+
+  From there, you can access them in your Python code. You can then read them like this:
+
+  ```python
+  import os
+
+  stack_project_id = os.getenv("STACK_PROJECT_ID")
+  stack_publishable_client_key = os.getenv("STACK_PUBLISHABLE_CLIENT_KEY")
+  stack_secret_server_key = os.getenv("STACK_SECRET_SERVER_KEY")
+  ```
+
+  ### Make a request
+
+  Next, create a helper function to make requests to the Stack Auth API:
+
+  ```python
+  import requests
+
+  def stack_auth_request(method, endpoint, **kwargs):
+    res = requests.request(
+      method,
+      f'https://api.stack-auth.com/{endpoint}',
+      headers={
+        'x-stack-access-type': 'server',  # or 'client' if you're only accessing the client API
+        'x-stack-project-id': stack_project_id,
+        'x-stack-publishable-client-key': stack_publishable_client_key,
+        'x-stack-secret-server-key': stack_secret_server_key,  # not necessary if access type is 'client'
+        **kwargs.pop('headers', {}),
+      },
+      **kwargs,
+    )
+    if res.status_code >= 400:
+      raise Exception(f"Stack Auth API request failed with {res.status_code}: {res.text}")
+    return res.json()
+
+  print(stack_auth_request('GET', '/api/v1/projects/current'))
+  ```
+
+  ### Retrieve the access tokens
+
+  If you're building a backend server, most likely you'll want to use the currently signed in user's access token. Most normally, you would send this with all your requests to the backend in an HTTP header.
+
+  In Stack Auth's JavaScript SDK, you can retrieve the access token [from the `stackClientApp` object](/sdk/types/user#currentusergetauthjson). Then, you can use said access token to make requests to Stack Auth:
+
+  ```python
+  access_token = # access token retrieved from the JavaScript SDK
+
+  print(stack_auth_request('GET', '/api/v1/users/me', headers={
+    'x-stack-access-token': access_token,
+  }))
+  ```
+
+  ### Done!
+</Steps>
+
+## Next steps
+
+Check out the [REST API documentation](../rest-api/overview.mdx) to learn more about the available endpoints and how to use them in your Python application.
+
 {/* END_PLATFORM */}
diff --git a/docs/fern/docs/pages-template/overview.mdx b/docs/fern/docs/pages-template/overview.mdx
@@ -22,13 +22,15 @@ You can get started in five minutes with our [setup guide](./getting-started/set
     Use our pre-built React components, or create your own
   </Card>
   {/* END_PLATFORM */}
+  {/* IF_PLATFORM: js-like */}
   <Card 
     title="SDK Reference"
     icon="fa-regular fa-file-lines" 
     href="/sdk"
   >
-    Learn how to use Stack's SDK
+    Learn how to use Stack Auth's SDK
   </Card>
+  {/* END_PLATFORM */}
   <Card 
     title="REST API Reference"
     icon="fa-solid fa-code" 
@@ -40,17 +42,17 @@ You can get started in five minutes with our [setup guide](./getting-started/set
 
 Still have questions? Check out our [FAQ](/faq) or [join our Discord](https://discord.stack-auth.com).
 
-## Why Choose Stack?
+## Why Choose Stack Auth?
 
 Authentication is inherently difficult. Few things are more sensitive than user data and more complex than cryptography. Not surprisingly, many online businesses struggle to get it right.
 
 The optimal authentication solution should be secure, yet approachable. If developers need to worry about JWTs, OAuth flows, or password hashing, then the authentication solution has failed its purpose. If an authentication solution uses closed-source, unauditable code for the most critical parts of your application, then we have failed.
 
 In truth, the authentication services industry has collectively failed. It's dominated by proprietary giants with predatory "bait-and-switch" pricing, providing no transparency into their codebase and delivering a subpar developer experience — because they know enterprises will pay more if setting up auth systems is painful.
 
-That's why we built Stack. Integrating secure authentication into your app should take **5 minutes**, not 5 days.
+That's why we built Stack Auth. Integrating secure authentication into your app should take **5 minutes**, not 5 days.
 
-At the core of Stack are deep integrations into frontend and backend frameworks. We offer the best developer experience with Next.js. Instead of providing mediocre support for numerous frameworks, we focused on making a few integrations excellent before adding new ones. We also offer a cross-compatible REST API as a fallback.
+At the core of Stack Auth are deep integrations into frontend and backend frameworks. We offer the best developer experience with Next.js. Instead of providing mediocre support for numerous frameworks, we focused on making a few integrations excellent before adding new ones. We also offer a cross-compatible REST API as a fallback.
 
 Here's an example. To get the current user, simply call:
 
@@ -61,7 +63,7 @@ export function MyComponent() {
 }
 ```
 
-That's it! Stack will either return a User object or redirect the user to the login page.
+That's it! Stack Auth will either return a User object or redirect the user to the login page.
 
 You can also add a button to change the user's name:
 
@@ -100,9 +102,9 @@ To manage everything efficiently, there is a powerful admin dashboard:
 
 ![Stack dashboard](./imgs/dashboard.png)
 
-Best of all, Stack is **100% open-source**. This means the client, server, dashboard, and even this documentation you're reading right now. Check out our [GitHub](https://github.com/stack-auth/stack-auth) to open an issue or pull request.
+Best of all, Stack Auth is **100% open-source**. This means the client, server, dashboard, and even this documentation you're reading right now. Check out our [GitHub](https://github.com/stack-auth/stack-auth) to open an issue or pull request.
 
-This is just a glimpse of what Stack can do. Stack also handles many other tasks like backend integration, data storage, emails, teams, permissions, and more, which you will learn about later in the documentation.
+This is just a glimpse of what Stack Auth can do. We also handle many other tasks like backend integration, data storage, emails, teams, permissions, and more, which you will learn about later in the documentation.
 
 If this sounds interesting, [get started](/getting-started/setup) with our interactive setup wizard, or join [our Discord community](https://discord.stack-auth.com) to ask questions and get help from our team.
 
diff --git a/docs/fern/docs/pages-template/sdk/types/user.mdx b/docs/fern/docs/pages-template/sdk/types/user.mdx
@@ -1058,7 +1058,7 @@ requests. Similar to `getAuthJson`, but specifically for HTTP requests.
 
 If you are using `tokenStore: "cookie"`, you don't need this for same-origin requests. However, most
 browsers now disable third-party cookies by default, so we must pass authentication tokens by header instead
-if the client and server are on different hostnames.
+if the client and server are on different origins.
 
 This function returns a header object that can be used with `fetch` or other HTTP request libraries to send
 authenticated requests.
diff --git a/package.json b/package.json
@@ -5,8 +5,8 @@
   "repository": "",
   "scripts": {
     "pre-no-codegen": "npx -y only-allow pnpm",
-    "pre-preinstall": "npx -y only-allow pnpm && node -e \"if(process.env.STACK_SKIP_TEMPLATE_GENERATION !== 'true') require('child_process').execSync('npx --package=tsx tsx ./scripts/generate-sdks.ts')\"",
-    "pre": "pnpm pre-preinstall && node -e \"if(process.env.STACK_SKIP_TEMPLATE_GENERATION !== 'true') { require('child_process').execSync('pnpm run generate-docs') }\"",
+    "pre-preinstall": "npx -y only-allow pnpm && node -e \"if(process.env.STACK_SKIP_TEMPLATE_GENERATION !== 'true') require('child_process').execSync('npx --package=tsx tsx ./scripts/generate-sdks.ts', {stdio: 'inherit'})\"",
+    "pre": "pnpm pre-preinstall && node -e \"if(process.env.STACK_SKIP_TEMPLATE_GENERATION !== 'true') { require('child_process').execSync('pnpm run generate-docs', {stdio: 'inherit'}) }\"",
     "preinstall": "pnpm pre-preinstall",
     "typecheck": "pnpm pre && turbo typecheck",
     "build:dev": "pnpm pre && NODE_ENV=development pnpm run build",
diff --git a/packages/template/src/lib/stack-app/users/index.ts b/packages/template/src/lib/stack-app/users/index.ts
@@ -32,7 +32,7 @@ export type Auth = {
    *
    * If you are using `tokenStore: "cookie"`, you don't need this for same-origin requests. However, most
    * browsers now disable third-party cookies by default, so we must pass authentication tokens by header instead
-   * if the client and server are on different hostnames.
+   * if the client and server are on different origins.
    *
    * This function returns a header object that can be used with `fetch` or other HTTP request libraries to send
    * authenticated requests.
diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts
@@ -69,7 +69,7 @@ const docsDir = path.resolve(__dirname, "..", "docs", "fern");
 const templateDir = path.join(docsDir, "docs", "pages-template");
 const ymlTemplatePath = path.join(docsDir, "docs-template.yml");
 
-for (const platform of ["next", "js", "react"]) {
+for (const platform of ["next", "js", "react", "python"]) {
   const destDir = path.join(docsDir, 'docs', `pages-${platform}`);
 
   const mainYmlContent = fs.readFileSync(ymlTemplatePath, "utf-8");
diff --git a/scripts/utils.ts b/scripts/utils.ts
@@ -6,10 +6,11 @@ export const COMMENT_LINE = "THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT E
 export const COMMENT_BLOCK = `\n//===========================================\n// ${COMMENT_LINE}\n//===========================================\n`
 
 export const PLATFORMS = {
-  "next": ['next', 'react-like'],
-  "js": ['js'],
-  "react": ['react', 'react-like'],
-  "template": ['template', 'react-like', 'next', 'js']
+  "next": ['next', 'react-like', 'js-like'],
+  "js": ['js', 'js-like'],
+  "react": ['react', 'react-like', 'js-like'],
+  "template": ['template', 'react-like', 'next', 'js', 'js-like', 'python-like'],
+  "python": ['python', 'python-like'],
 }
 
 

Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,7 @@ export type Auth = {`
`32`	`32`	`*`
`33`	`33`	* If you are using `tokenStore: "cookie"`, you don't need this for same-origin requests. However, most
`34`	`34`	`* browsers now disable third-party cookies by default, so we must pass authentication tokens by header instead`
`35`		`- * if the client and server are on different hostnames.`
	`35`	`+ * if the client and server are on different origins.`
`36`	`36`	`*`
`37`	`37`	* This function returns a header object that can be used with `fetch` or other HTTP request libraries to send
`38`	`38`	`* authenticated requests.`