Authentication

Authentication identifies the caller. Authorization decides which records and actions that caller can access. In an Apso service, the selected auth provider populates a normalized request context that generated tenant scoping and custom extensions can use.

Request lifecycleOne request, with every backend boundary visible.

Authenticated

01ClientServer component, mobile app, or service
02SDK or RESTTyped operation and validated payload
03IdentitySession, JWT, or API key context
04Tenant scopeAuthorization and row boundary
05ServiceGenerated route, product logic, and database

Keep privileged credentials on the server and pass only verified identity and tenant context into the generated service.

Choose a strategy

Caller	Strategy	Provider value
Web application with owned sessions	Better Auth or a custom database session	`better-auth`, `custom-db-session`
User authenticated by an external identity platform	Verified JWT	`auth0`, `clerk`, `cognito`
Trusted machine represented in the application data model	Application API key	`api-key`
Trusted server calling a hosted Apso service	Hosted service key	Manage in the Apso Cloud API Keys view

Configure `.apsorc`

Add one top-level auth object. This JWT example maps the provider claims into Apso’s auth context:

.apsorc (excerpt)


{
  "auth": {
    "provider": "cognito",
    "jwt": {
      "issuer": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example",
      "audience": "your-client-id",
      "algorithms": ["RS256"]
    },
    "claims": {
      "userId": "sub",
      "email": "email",
      "workspaceId": "custom:workspace_id",
      "roles": "cognito:groups"
    }
  }
}

Run apso generate, inspect the generated guard, and test invalid, valid, and cross-tenant requests.

Connect authorization

Use scopeBy for resource isolation and extensions for product-specific policies:

.apsorc (entity excerpt)


{
  "name": "Project",
  "scopeBy": "workspaceId",
  "scopeOptions": {
    "injectOnCreate": true,
    "enforceOn": ["find", "get", "create", "update", "delete"],
    "bypassRoles": ["system_admin"]
  },
  "fields": [
    { "name": "name", "type": "text" }
  ]
}

A valid token does not prove tenant membership or permission for a product action. Test tenant filters, role bypasses, and custom approval rules separately.

Client rules

Keep hosted service keys in a server environment.
Send user JWTs over HTTPS in the Authorization: Bearer header when using JWT auth.
Prefer HTTP-only, secure cookies for web sessions.
Store mobile user tokens in Keychain, Keystore, or the platform’s secure storage.
Never log raw session tokens or API keys.

Build a database-backed web session flow

Better Auth

Configure Auth0, Clerk, Cognito, or a custom extension

External providers

Model and validate machine credentials inside the service

Application API keys

Create and rotate credentials in Apso Cloud

Hosted service keys