Overview

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).

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.

Client-Side Authentication

For requests from browsers, mobile apps, or other client-side environments:

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:

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.

To see how to use these headers in various programming languages, see the examples.

Getting Started

1. Choose the right API

   Select the API category that matches your use case.

2. Set up authentication

   Configure the appropriate authentication method (sessions, API keys, or webhook verification).

3. Make requests

   Use the documented endpoints with proper authentication headers.

4. Handle responses

   Process the API responses according to the documentation and error handling guidelines.

FAQ

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.

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.

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.

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.

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.

Need Help?

Getting Started Guide

Check the Getting Started Guide for initial setup.

Documentation

Visit the Concepts section for Stack Auth fundamentals.

Discord Community

Join the Discord community for support and discussions.