Docs/Projects

Projects

A project is the container for everything in Astapa. Each project represents one app or service and gets its own client_id, client_secret, redirect URIs, end users, plans, and analytics. Think of it as a namespace for your entire auth and billing setup.

Project types

When creating a project, you choose a type that determines how authentication works:

🌐

Web

Standard OAuth 2.0 authorization code flow. For web apps, SPAs, and mobile apps.

🤖

MCP

Machine-to-machine auth via client_credentials. For AI agents and MCP servers.

🔀

Hybrid

Both flows enabled. For apps that serve both human users and AI agents.

Create a project

You can create projects from the dashboard (recommended) or via the API. Either way, you'll get back a client_id and client_secret.

create-project.tstypescript

const res = await fetch("https://astapa.com/api/platform/projects", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Cookie": "session=your_session_cookie",
  },
  body: JSON.stringify({
    name: "My SaaS App",
    redirect_uris: ["https://myapp.com/callback"],
  }),
});

const { project } = await res.json();
// project.client_id     → "proj_abc123..."
// project.client_secret → "sec_xyz789..." (shown once!)

Store the secret immediately

The client_secret is only returned once at creation time. If you lose it, you'll need to regenerate it (which invalidates the old one).

Redirect URIs

Redirect URIs are the allowed callback URLs for the OAuth flow. After a user authenticates, we redirect them to one of these URLs with an authorization code. Rules:

Production URIs must use HTTPS
http://localhost is allowed for development
Every project must have at least one redirect URI
The redirect_uri in the auth request must exactly match one of the registered URIs

Authentication

All project management endpoints require a valid session cookie — you must be logged in to astapa.com as the builder who owns the project. These are builder-facing APIs, not end-user-facing.

End-user-facing APIs (token exchange, userinfo, claims) use client_id + client_secret instead. See the Authentication docs.

API reference