Authentication

Apso lets the generated service enforce authentication while your product controls who issues sessions or tokens. Choose the provider based on the client and trust boundary, then map the authenticated identity into tenant scope and roles.

Supported strategies

This .apsorc configuration controls generated application authentication. A hosted Apso service key is managed separately in the Apso Cloud API Keys view.

Better Auth

Use Better Auth for a database-backed session model owned by the application:

{
  "auth": {
    "provider": "better-auth",
    "sessionEntity": "Session",
    "userEntity": "User",
    "accountUserEntity": "AccountUser",
    "organizationField": "organizationId",
    "roleField": "role"
  }
}

The entity names must match the models in the schema. The generated auth guard resolves the session into a normalized request context with user, organization, and role information.

JWT provider

Use a JWT strategy when Auth0, Clerk, or Cognito issues the user token. Configure the issuer, audience, and claim paths used by the product:

{
  "auth": {
    "provider": "auth0",
    "jwt": {
      "issuer": "https://your-tenant.example.com/",
      "audience": "https://api.example.com",
      "algorithms": ["RS256"]
    },
    "claims": {
      "userId": "sub",
      "email": "email",
      "workspaceId": "org_id",
      "roles": "roles"
    },
    "userEntity": "User"
  }
}

The provider can supply jwksUri. When omitted, the generated strategy derives the standard JWKS location from the issuer.

Application API key

Use this strategy for machine identities represented in the service schema:

{
  "auth": {
    "provider": "api-key",
    "apiKeyHeader": "x-api-key",
    "apiKeyEntity": "ApiKey",
    "workspaceField": "workspaceId",
    "roleField": "role"
  }
}

Store only a hash of a credential when implementing the ApiKey entity and its extensions. Return the raw value once at creation time.

Authentication and tenant scope

scopeBy uses values from the normalized auth context. For a workspace-scoped entity:

{
  "name": "Project",
  "scopeBy": "workspaceId",
  "fields": [
    { "name": "name", "type": "text" }
  ]
}

The auth strategy must populate workspaceId for the generated scope guard to filter reads, inject scope on creates, and verify ownership on updates and deletes.

Client boundary

Verification checklist

1. Generate the auth guard and inspect its expected headers or cookie.
2. Verify a valid caller can read one authorized resource.
3. Verify a missing or invalid credential is rejected.
4. Verify a caller cannot cross the configured tenant scope.
5. Verify role bypasses are limited and covered by tests.