stack/docs-mintlify/api/overview.mdx

---
title: "Overview"
description: "Complete REST API documentation for Stack Auth"
---

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

Stack Auth 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.stack-auth.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.stack-auth.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 concept documentation on [StackApp](/guides/going-further/stack-app#client-vs-server).

  </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 concept documentation on [StackApp](/guides/going-further/stack-app#client-vs-server).

  </Accordion>

  <Accordion title="How do I handle API errors?">
    Stack Auth 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, Stack Auth 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 Stack Auth fundamentals.
  </Card>
  <Card title="Discord Community" href="https://discord.stack-auth.com">
    Join the Discord community for support and discussions.
  </Card>
</Columns>