mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-04 21:04:37 +08:00
8043109bae
# Conflicts: # docs-mintlify/api/overview.mdx # docs-mintlify/docs.json # docs-mintlify/guides/going-further/hexclave-app.mdx # docs-mintlify/guides/going-further/user-metadata.mdx # docs-mintlify/guides/other/tutorials/build-a-saas-with-hexclave.mdx # docs-mintlify/guides/other/tutorials/ship-production-ready-auth.mdx # docs-mintlify/index.mdx # docs-mintlify/llms-full.txt # docs-mintlify/sdk/objects/hexclave-app.mdx # docs-mintlify/sdk/types/project.mdx # docs-mintlify/sdk/types/team.mdx # docs-mintlify/snippets/hexclave-agent-reminders.jsx # packages/init-stack/src/index.ts # packages/shared/src/ai/unified-prompts/skill-site-prompt-parts/docs-json.generated.ts
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 see how to use these headers in various programming languages, see the
|
|
[examples](/guides/going-further/backend-integration).
|
|
</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>
|