Docs/Users

Users

End users are the people who sign in to your app through Astapa. You don't create them — they appear automatically after their first login. From there, you can list, search, deactivate, revoke tokens, and attach custom claims to any user.

How users are created

When someone completes the hosted login flow for your project, Astapa creates an end user record automatically. No manual creation needed — just redirect users to login and we handle the rest.

Auto-created

Users appear after their first successful login — email, Google, or GitHub

Project-scoped

Each user belongs to one project. Same email, different projects = different users

OAuth linked

Google and GitHub accounts are linked automatically on first login

List and search users

Fetch paginated user lists from the dashboard API. Optionally filter by email with the search parameter.

list-users.tstypescript

// List users (paginated)
const res = await fetch(
  "https://astapa.com/api/platform/projects/{projectId}/users?page=1&page_size=20",
  { headers: { Cookie: "session=..." } }
);
const { users, total, page, page_size } = await res.json();

// Search by email
const search = await fetch(
  "https://astapa.com/api/platform/projects/{projectId}/users?search=john@",
  { headers: { Cookie: "session=..." } }
);

Deactivate and revoke

Two ways to cut off access for a user:

Deactivate

Set is_active: false — the user can't log in anymore. Reversible.

PATCH /projects/:id/users/:userId

Revoke tokens

Invalidate all refresh tokens. Forces re-authentication on next request.

POST /projects/:id/users/:userId/revoke

When to use which?

Deactivate for permanent bans or account suspensions. Revoke tokens when you need to force a re-login (e.g. after a password change or security incident) but want the user to keep access.

Custom claims

Attach key-value metadata to any user. Claims are included in every access token, so your app can check user.claims.plan or user.claims.role without an extra API call.

set-claims.tstypescript

// Set claims from your backend (server-to-server)
await fetch("https://astapa.com/api/platform/claims", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: process.env.CLIENT_ID,
    client_secret: process.env.CLIENT_SECRET,
    email: "user@example.com",
    claims: { plan: "pro", role: "admin" },
  }),
});

Claims in the JWT

Claims appear under custom_claims in the decoded JWT. Total payload must be under 4KB. See the Custom Claims docs for the full API.

Server-to-server user lookup

Need to look up a user from your backend without a dashboard session? Use client credentials to query by email — useful in webhook handlers, background jobs, or admin tools.

lookup.tstypescript

const res = await fetch(
  "https://astapa.com/api/platform/users?" + new URLSearchParams({
    client_id: process.env.CLIENT_ID!,
    client_secret: process.env.CLIENT_SECRET!,
    email: "user@example.com",
  }),
);
const { user } = await res.json();
// user.id, user.email, user.claims, user.is_active, ...

API reference

Dashboard APIs

These endpoints use session cookie auth — for use from the Astapa dashboard or your admin panel.

Claims APIs (dashboard)

Server-to-server APIs

Use client credentials from your backend — no session cookie needed.