mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-04 21:04:37 +08:00
c14a9dd3d0
## Stack Auth → Hexclave rename — PR 5 (internal symbols, paths,
packages, brand strings)
PR 5 finishes the **internal / non-wire** half of the Stack→Hexclave
rename. It only touches things where nothing outside the repo depends on
the exact name: internal symbols, file/dir names, the
`@stackframe/template` package, and residual brand strings. Plan +
progress are in `HEXCLAVE-RENAME-PR5-PLAN.md`.
Every step was verified green (`pnpm typecheck` + `pnpm lint`, 28/28)
and committed as its own checkpoint, then a fan-out of review agents
audited all commits and the findings were fixed.
### What changed
- **Internal symbols** (`@hexclave/shared`, `packages/template`, apps):
`stack*`/`Stack*` → `hexclave*`/`Hexclave*` — incl.
`stackGlobalsSymbol`, the `_Stack*AppImpl` classes,
`stackAppInternalsSymbol`, `StackContext`, `getStackStripe`, etc. The
`stack*App` local-variable convention
(`stackServerApp`/`stackClientApp`/…) was renamed across 175
source/example/doc files.
- **File renames**: `hexclave-handler/provider/context.tsx`,
`backend/hexclave.tsx`, `internal-tool/hexclave.ts`,
`hexclave-app-internals.ts`.
- **Directory renames**: `lib/hexclave-app`, `hexclave-companion`,
`[...hexclave]` route segment, `skills/hexclave`,
`dashboard/src/hexclave`, and the package dirs
**`packages/{next,shared,ui,sc,cli}`** (dropping the `stack-` prefix to
match the `@hexclave/*` npm names).
- **Packages**: `@stackframe/template` → `@hexclave/template`; **deleted
`packages/init-stack`** (onboarding lives in `@hexclave/cli init`; the
published npm package is untouched).
- **Brand strings**: reworded `Stack Auth`/`Stack dashboard` prose in
code + docs-mintlify, renamed `hexclave-app.mdx`/`use-hexclave-app.mdx`
with redirects, regenerated OpenAPI, updated coupled e2e assertions;
`doctor`/`init` now prefer `hexclave.config.ts`.
### Intentionally kept (verified, not oversights)
Wire/compat identifiers (`x-stack-*` headers, `stack-*` cookies,
`STACK_*` env names, `*.stack-auth.com`, `stackauth_`, `ask_stack_auth`,
query params), public `Stack*` SDK aliases, crypto/JWT/vault
domain-separation tags, `*-brand-sentinel`s, the
`Symbol.for("StackAuth--…")` string, `_stack_sync_metadata`, Postgres
`stackframe` / docker image names, the `stack-auth-logo*.svg` (used by
the rebrand modal), and `migration.mdx` / "formerly known as Stack Auth"
notes. False positives (Phosphor `StackIcon`/`StackSimple`, `TanStack`,
`OrbStack`, `stackable`/`Stacked` charts) left alone.
### Review pass
Six review agents audited all commits. Found + fixed one real bug — a
build script (`bundle-type-definitions.ts`) hardcoded the old
`lib/stack-app` glob path (not an import, so typecheck/lint were blind),
silently emptying the dashboard AI type bundle — plus stale comments, a
dead CI env var, and stale `.gitignore`/`.dockerignore` entries.
Cross-cutting audit confirmed **zero wire-compat identifiers were
accidentally renamed**.
### ⚠️ Verification note
`typecheck` + `lint` are fully green locally. The **e2e suite was not
run** (needs a live backend+DB), so the brand-string assertion +
OpenAPI-regen changes are verified by grep/codegen only — please let CI
exercise e2e to confirm.
### Base-branch note
This branch was forked from the local-only `cl/friendly-lewin-72293f`
(not on origin, no separate PR), so this PR against `dev` also carries
that branch's ~11 preceding Hexclave-rename commits (config-file rename,
env-var dual-read, AI setup-prompt rebrand). If those should land
separately, re-parent before merge.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Finishes the internal Stack Auth → Hexclave rename and cleans up
remaining stragglers, including dev-tool and prompt copy. All changes
are internal-only; public/wire APIs remain unchanged. Re-merged `dev`
and resolved the payments create-purchase-url conflict.
- **Refactors**
- Internal symbols: stack*/Stack* → hexclave*/Hexclave* (e.g.,
`getHexclaveServerApp` via `@/hexclave`, `getHexclaveStripe`,
`hexclaveAppInternalsSymbol`, `hexclaveSchemaInfo`, Prisma
`__hexclave_*`, `data-hexclave-handler-page`, Stripe mock
`hexclavePortPrefix`).
- Files/dirs: moved to `lib/hexclave-app`; handler route
`[...hexclave]`; backend entry `src/hexclave.tsx`; dashboard internals
`hexclave-app-internals`; companion `hexclave-companion`; dropped
`stack-` prefix across package dirs
(`packages/{shared,ui,sc,cli,next}`); workflows/emulator paths now
`packages/cli`; Quetzal codegen env at `packages/next/.env.local`.
- Packages/docs: `@stackframe/template` → `@hexclave/template`; removed
`packages/init-stack`; regenerated OpenAPI and updated docs
slugs/redirects for hexclave-app/use-hexclave-app.
- Brand strings/prompts: reworded remaining “Stack” dashboard strings to
Hexclave; updated dev-tool copy and prompts; `doctor/init` now prefer
`hexclave.config.ts`. Kept all wire-compat identifiers and public
aliases (`x-stack-*`, `stack-*` cookies, `STACK_*` env,
`*.stack-auth.com`, `Stack*` SDK names).
- Rebased/merged onto latest `dev`: retained `@hexclave/template`, kept
`src` in published files, refreshed setup-prompt imports and docs JSON,
adopted 1.0.5 version bumps, and re-merged `dev` again (resolved
`create-purchase-url` with `getHexclaveStripe`).
- **Bug Fixes**
- Restored dashboard AI type bundle by pointing the glob to
`packages/template/src/lib/hexclave-app`.
- Addressed rename leftovers: updated lingering `@/stack` imports and
CSS selector, fixed schema/meta and port-prefix expansions, and aligned
emulator commands to `packages/cli`.
- CI/build: removed a dead env var and stale ignore entries; fixed
Docker by renaming `STACK_SKIP_TEMPLATE_GENERATION` →
`HEXCLAVE_SKIP_TEMPLATE_GENERATION`.
<sup>Written for commit 3c1af3bff3.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1547?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
132 lines
6.0 KiB
Plaintext
132 lines
6.0 KiB
Plaintext
---
|
|
title: "Overview"
|
|
description: "Complete REST API documentation for Hexclave"
|
|
---
|
|
|
|
Stack offers a REST API for backends & frontends of any programming language or framework. This API is used to authenticate users, manage user data, and more.
|
|
|
|
## Authentication
|
|
|
|
Hexclave uses different authentication patterns depending on whether you're making requests from client-side code (browser, mobile app) or server-side code (your backend).
|
|
|
|
<Warning>
|
|
**Security Critical**: Never expose your secret server key (`ssk_...`) in
|
|
client-side code, browser requests, or any publicly accessible location.
|
|
Server keys should only be used in secure backend environments.
|
|
</Warning>
|
|
|
|
### Client-Side Authentication
|
|
|
|
For requests from browsers, mobile apps, or other client-side environments:
|
|
|
|
```bash
|
|
curl https://api.hexclave.com/api/v1/ \
|
|
-H "X-Stack-Access-Type: client" \
|
|
-H "X-Stack-Project-Id: <your project UUID>" \
|
|
-H "X-Stack-Publishable-Client-Key: pck_<your publishable client key>" \
|
|
-H "X-Stack-Access-Token: <the current user's access token>"
|
|
```
|
|
|
|
### Server-Side Authentication
|
|
|
|
For requests from your secure backend server:
|
|
|
|
```bash
|
|
curl https://api.hexclave.com/api/v1/ \
|
|
-H "X-Stack-Access-Type: server" \
|
|
-H "X-Stack-Project-Id: <your project UUID>" \
|
|
-H "X-Stack-Secret-Server-Key: ssk_<your secret server key>"
|
|
```
|
|
|
|
### Authentication Headers
|
|
|
|
| Header | Type | Used In | Description |
|
|
| -------------------------------- | ---------------------- | ----------- | ---------------------------------------------------------------------------------------- |
|
|
| `X-Stack-Access-Type` | `"client" \| "server"` | Both | Required. Use `"client"` for frontend/browser requests, `"server"` for backend requests. |
|
|
| `X-Stack-Project-Id` | UUID | Both | Required. Your project ID from the Stack dashboard. |
|
|
| `X-Stack-Publishable-Client-Key` | string | Client only | Required for client access. Safe to expose in frontend code. Starts with `pck_`. |
|
|
| `X-Stack-Secret-Server-Key` | string | Server only | Required for server access. **Never expose in client code**. Starts with `ssk_`. |
|
|
| `X-Stack-Access-Token` | string | Client only | Optional. The current user's access token. Used to act on behalf of a specific user. |
|
|
|
|
<Info>
|
|
To set up a backend in JavaScript, Python, or another language using the REST
|
|
API, see [Setup](/guides/getting-started/setup).
|
|
</Info>
|
|
|
|
## Getting Started
|
|
|
|
<Steps>
|
|
<Step title="Choose the right API">
|
|
Select the API category that matches your use case.
|
|
</Step>
|
|
<Step title="Set up authentication">
|
|
Configure the appropriate authentication method (sessions, API keys, or
|
|
webhook verification).
|
|
</Step>
|
|
<Step title="Make requests">
|
|
Use the documented endpoints with proper authentication headers.
|
|
</Step>
|
|
<Step title="Handle responses">
|
|
Process the API responses according to the documentation and error handling
|
|
guidelines.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## FAQ
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Which languages are supported?">
|
|
Any language that has the ability to send HTTP requests can use the Stack REST API. This includes JavaScript, Python, Ruby, Java, Go, C#, Dart, and many more.
|
|
</Accordion>
|
|
|
|
<Accordion title="Should I use client or server access type?">
|
|
**Client access type** (`X-Stack-Access-Type: client`) is for client-side applications like browsers and mobile apps. Client APIs can only read and update the currently authenticated user's data. Use your publishable client key (`pck_...`) - it's safe to include in frontend code.
|
|
|
|
**Server access type** (`X-Stack-Access-Type: server`) is for your secure backend server. It has full access over all user data using your secret server key (`ssk_...`).
|
|
|
|
Never use server access type or secret server keys in client-side code, browser requests, or any publicly accessible location. Always keep server keys secure on your backend.
|
|
|
|
For more information, see the [`HexclaveClientApp` and `HexclaveServerApp` SDK reference](/sdk/objects/hexclave-app).
|
|
|
|
</Accordion>
|
|
|
|
<Accordion title="What is this 'admin' access type that I see?">
|
|
If you'd like to build your own version of the Stack dashboard (or update project configuration programmatically), you can use the `admin` access type. These endpoints are very dangerous and you should only use them if you know what you're doing.
|
|
|
|
For more information, see the [`HexclaveClientApp` and `HexclaveServerApp` SDK reference](/sdk/objects/hexclave-app).
|
|
|
|
</Accordion>
|
|
|
|
<Accordion title="How do I handle API errors?">
|
|
Hexclave API returns standard HTTP status codes. Common error responses include:
|
|
|
|
- `400 Bad Request` - Invalid request parameters
|
|
- `401 Unauthorized` - Invalid or missing authentication
|
|
- `403 Forbidden` - Insufficient permissions
|
|
- `404 Not Found` - Resource not found
|
|
- `429 Too Many Requests` - Rate limit exceeded
|
|
- `500 Internal Server Error` - Server error
|
|
|
|
Error responses include a JSON body with additional details about the error.
|
|
|
|
</Accordion>
|
|
|
|
<Accordion title="Are there rate limits?">
|
|
Yes, Hexclave implements rate limiting to ensure fair usage and system stability. Rate limits vary by endpoint and access type. When you exceed the rate limit, you'll receive a `429 Too Many Requests` response with headers indicating when you can retry.
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## Need Help?
|
|
|
|
<Columns cols={3}>
|
|
<Card title="Getting Started Guide" href="/guides/getting-started/setup">
|
|
Check the Getting Started Guide for initial setup.
|
|
</Card>
|
|
<Card title="Documentation" href="/guides/getting-started/setup">
|
|
Visit the Concepts section for Hexclave fundamentals.
|
|
</Card>
|
|
<Card title="Discord Community" href="https://discord.hexclave.com">
|
|
Join the Discord community for support and discussions.
|
|
</Card>
|
|
</Columns>
|