Skip to content

Server API (Go and Gin) ​

This is the API of the code selfauth init --backend gin puts in your project: internal/ginauth (the Gin adapter) and internal/auth (the core). It's your code, so you call it directly. The examples assume the module path github.com/you/my-api.

Setup ​

cmd/server/main.go and internal/app/ already do this for you:

go
a, err := app.NewAuth(app.AuthOptions{
	Config: cfg, Env: env, Store: stores.Store, Mailer: mailer,
	RateLimitStore: stores.RateLimitStore, Logger: logger,
})
router, err := app.NewRouter(app.Options{Config: cfg, Auth: a, Logger: logger, Mount: func(r *gin.Engine, a *ginauth.Auth) {
	routes.Register(r, a, stores.DB)
}})

NewAuth refuses unsafe production settings, meaning an insecure cookie or an app base URL that isn't https. NewRouter builds the Gin engine in a fixed order: request id and recovery, request logging, the JSON body limit, SelfAuth's CORS, session and CSRF middleware, GET /health, the /auth routes, your routes (Mount), and finally the 404 handler.

*ginauth.Auth ​

MethodWhat it does
Middleware() []gin.HandlerFuncCORS, session lookup and CSRF verification. Mounted for you by NewRouter
RegisterRoutes(group *gin.RouterGroup)Registers the /auth routes. Called by NewRouter
Context(c) *auth.ContextThe signed-in context, or nil. Has UserID, Roles, Permissions (through the embedded Subject), User and Session
RequireAuth() gin.HandlerFuncGuard: 401 UNAUTHENTICATED without a valid session
RequirePermission(p string) gin.HandlerFuncGuard: 401 without a session, 403 FORBIDDEN without permission p. Panics when the route is defined if p is not declared in the configuration
AuthorizeResource(p string, resource func(c *gin.Context) (resourceType, id string)) gin.HandlerFuncGuard that runs the policy registered for the resource type. A denied resource answers 404 NOT_FOUND; a type with no policy answers 403 FORBIDDEN
ProtectedRoutes(group gin.IRoutes) *ProtectedWraps a group so each route is denied unless a guard explicitly allowed it. Methods: GET, POST, PUT, PATCH, DELETE(path, handlers...)
Policies() *auth.PolicyRegistryRegister(resourceType, policy) registers a resource policy
Service() *auth.ServiceThe framework-independent core behind the routes, for custom flows
Abort(c, err)Stops the request with a SelfAuth error in the standard envelope

As in the TypeScript API, only RequirePermission and AuthorizeResource count as authorization inside ProtectedRoutes. RequireAuth on its own doesn't. See Protect routes.

Helpers in internal/auth ​

NamePurpose
auth.OwnershipPolicy(load)Policy: allows an action if the subject holds it and owns the resource, or holds the <action>_any permission. load func(ctx context.Context, id string) (*auth.Resource, error) must read from storage and return nil, nil when the resource does not exist
auth.OwnerFilter(subject, action)For list queries. Returns (ownerID, all, ok): filter by ownerID unless all; ok is false when the subject holds neither permission
auth.Resource{ Type, ID, OwnerID string }
auth.Subject{ UserID string, Roles []string, Permissions map[string]struct{} } with Has(permission) bool
auth.ResourcePolicyInterface with Load(ctx, id) and Authorize(subject, action, resource) bool, for rules other than ownership
auth.Fail(code)Creates a SelfAuth error. Codes: auth.Unauthenticated, auth.Forbidden, auth.NotFound, auth.ValidationFailed, and so on
auth.MemoryMailer, auth.NewDevConsoleMailer(production bool)Mailers for tests and development
auth.MailerInterface your provider implements: Send(ctx, EmailMessage) error
auth.RoleDefinitions(cfg)The role map the seed writes to the database

Helpers in internal/httpx ​

NamePurpose
httpx.Body(c) auth.InputThe JSON object already parsed by SelfAuth's middleware (an empty map if none). Use it instead of c.ShouldBindJSON
httpx.WriteError(c, status, code, message, details)Writes the standard error envelope
httpx.AssignRequestID(), httpx.Recovery(logger), httpx.RequestLog(logger), httpx.JSONBody(limit)The middleware NewRouter installs

Configuration and environment (internal/config) ​

NamePurpose
config.Load(path)Reads, strictly decodes and validates selfauth.config.json
config.Parse(raw []byte)The same for bytes (used in tests)
config.LoadEnv(lookup)Reads and validates the environment (APP_ENV, PORT, SELFAUTH_APP_BASE_URL, ...). Returns every problem at once
config.OSLookuplookup for the real process environment
Env.Production()True when APP_ENV=production

Stores (internal/store) ​

store.New(ctx, cfg, env) opens the database from adapter.database (PostgreSQL, MySQL, SQLite or MongoDB) when DATABASE_URL is set, and the in-memory store in development otherwise. In production without DATABASE_URL it returns an error. A store implements the auth.Store and auth.RateLimitStore interfaces, and internal/store/storetest holds the shared tests every store has to pass.

Stores.DB is your routes' handle on the same database: DB.SQL is a *sql.DB on PostgreSQL, MySQL and SQLite, DB.Mongo a *mongo.Database on MongoDB. Both are nil on the in-memory store. routes.Register receives it as db.

Example: a guarded route ​

go
func Register(r *gin.Engine, a *ginauth.Auth, db store.DB) {
	api := r.Group("/api")
	api.GET("/me", a.RequireAuth(), func(c *gin.Context) {
		ctx := a.Context(c)
		c.JSON(http.StatusOK, gin.H{"email": ctx.User.Email, "roles": ctx.Roles})
	})
}

The Gin guide builds a complete example with its own table.

SelfAuth is MIT licensed. Generated code is also offered under 0BSD.