Docs/Overview

Overview

Astapa handles authentication and subscription state for your SaaS. Your users sign in on our hosted pages, we track which plan they're on, and your app reads a signed JWT to decide what to unlock.

Authentication

User signs in on Astapa's hosted login. Your server exchanges the authorization code for a JWT.

User

Clicks "Sign in"

Astapa hosted login

Email, Google, or GitHub

Your callback

Exchange code → JWT

POST /api/platform/token → response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "rt_a1b2c3...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Feature gating

You assign a plan to a user via the Claims API. The next JWT carries that plan. Your app reads it and gates features.

Your server

POST /api/platform/claims

Astapa

Stores plan on user

Next JWT

custom_claims.plan = "pro"

decoded JWT payload

{
  "sub": "42",
  "email": "user@example.com",
  "custom_claims": {
    "plan": "pro",
    "role": "admin"
  }
}

Token refresh

Access tokens expire after 1 hour. Use the refresh token to get a new one without re-authenticating. This is typically done transparently in middleware.

Middleware

JWT expired

Astapa token endpoint

grant_type=refresh_token

New access token

Fresh JWT, updated claims

Instant plan upgrade

After a purchase, set the new plan via Claims API, then immediately refresh the token. The user sees their new plan without waiting for the old JWT to expire.

Set claims

plan: "pro"

Refresh token

Get new JWT with updated plan

User sees Pro

Immediate, no delay

If you skip the refresh step, the user stays on the old plan until the JWT naturally expires (up to 1 hour).

Logout and revocation

Revoke all refresh tokens server-side, then clear cookies. The user can't refresh anymore.

Your server

POST /api/platform/revoke

Astapa

Invalidates all refresh tokens

Clear cookies