Environments Overview

Application environments for isolating development, staging, and production authentication data and configuration.

Environments let you run multiple isolated authentication contexts within a single Authsome application. Each environment has its own users, sessions, organizations, configuration, and API keys. A production environment's data is completely isolated from the development environment -- you can safely test authentication flows, schema changes, and plugin configurations in dev without touching production.

The Environment model

import "github.com/xraph/authsome/env"

type Environment struct {
    ID          id.ID             `json:"id"`         // aenv_ prefix
    AppID       string            `json:"app_id"`
    Name        string            `json:"name"`       // e.g. "Production"
    Slug        string            `json:"slug"`       // e.g. "production"
    Type        EnvironmentType   `json:"type"`
    Description string            `json:"description,omitempty"`
    Color       string            `json:"color,omitempty"`    // hex color for dashboard
    IsDefault   bool              `json:"is_default"`
    IsActive    bool              `json:"is_active"`
    Settings    EnvironmentSettings `json:"settings"`
    Metadata    map[string]string `json:"metadata,omitempty"`
    CreatedAt   time.Time         `json:"created_at"`
    UpdatedAt   time.Time         `json:"updated_at"`
}

Field	Description
`ID`	Globally unique identifier with `aenv_` prefix
`Name`	Human-readable name, e.g. `"Production"`, `"Staging"`, `"Development"`
`Slug`	URL-safe identifier used in API calls and environment switching, e.g. `"production"`
`Type`	One of the built-in types or `"custom"`
`Color`	Hex color code for visual identification in the dashboard (`#EF4444` for prod, `#F59E0B` for staging)
`IsDefault`	When `true`, this environment is used when no environment is specified in API calls
`IsActive`	When `false`, the environment is suspended and no authentication operations can complete
`Settings`	Per-environment configuration overrides

Environment types

const (
    EnvironmentTypeDevelopment EnvironmentType = "development"
    EnvironmentTypeStaging     EnvironmentType = "staging"
    EnvironmentTypeProduction  EnvironmentType = "production"
    EnvironmentTypeCustom      EnvironmentType = "custom"
)

Type	Default color	Typical use
`development`	`#3B82F6` (blue)	Local development and unit testing
`staging`	`#F59E0B` (amber)	Pre-production QA and integration testing
`production`	`#EF4444` (red)	Live user-facing environment
`custom`	`#8B5CF6` (purple)	Additional environments (preview, canary, region-specific)

Production environments are marked with a red indicator in the Authsome dashboard. Authsome will also show a confirmation dialog before performing destructive operations (like deleting users or revoking all sessions) in production environments.

Environment settings

Each environment carries its own settings that override the application defaults:

type EnvironmentSettings struct {
    // Session settings.
    SessionTTL            time.Duration `json:"session_ttl"`              // default 7d
    RefreshTokenTTL       time.Duration `json:"refresh_token_ttl"`        // default 30d
    MaxSessionsPerUser    int           `json:"max_sessions_per_user"`    // 0 = unlimited
    IdleSessionTimeout    time.Duration `json:"idle_session_timeout"`     // 0 = disabled

    // Password settings.
    MinPasswordLength     int           `json:"min_password_length"`      // default 8
    RequireSpecialChars   bool          `json:"require_special_chars"`
    RequireUppercase      bool          `json:"require_uppercase"`
    RequireNumbers        bool          `json:"require_numbers"`

    // Auth settings.
    MFARequired           bool          `json:"mfa_required"`
    AllowedAuthMethods    []string      `json:"allowed_auth_methods"`    // nil = all enabled plugins
    SelfRegistration      bool          `json:"self_registration"`       // default true

    // Security settings.
    IPBinding             string        `json:"ip_binding"`              // "disabled", "subnet", "strict"
    LockoutEnabled        bool          `json:"lockout_enabled"`
    LockoutMaxAttempts    int           `json:"lockout_max_attempts"`
    LockoutDuration       time.Duration `json:"lockout_duration"`
}

CRUD operations

Create an environment

import "github.com/xraph/authsome/env"

environment, err := auth.Environments().Create(ctx, &env.CreateInput{
    Name:        "Preview",
    Type:        env.EnvironmentTypeCustom,
    Description: "Short-lived preview environments for pull requests",
    Color:       "#10B981",
    Settings: env.EnvironmentSettings{
        SessionTTL:         2 * time.Hour,
        SelfRegistration:   false,
        MFARequired:        false,
        LockoutEnabled:     false,
    },
})
if err != nil {
    return err
}
fmt.Printf("created environment: id=%s slug=%s\n", environment.ID, environment.Slug)

Get an environment

// By ID.
e, err := auth.Environments().GetByID(ctx, envID)

// By slug.
e, err := auth.Environments().GetBySlug(ctx, "production")

// The default environment for the app.
e, err := auth.Environments().GetDefault(ctx)

Update an environment

updated, err := auth.Environments().Update(ctx, envID, &env.UpdateInput{
    Name:  "Production (US East)",
    Color: "#DC2626",
    Settings: &env.EnvironmentSettings{
        SessionTTL:         14 * 24 * time.Hour,
        MFARequired:        true,
        LockoutMaxAttempts: 5,
        LockoutDuration:    30 * time.Minute,
    },
})

Set the default environment

// Make this environment the default for the application.
err := auth.Environments().SetDefault(ctx, envID)

Only one environment can be the default at a time. Setting a new default automatically clears the flag from the previous default.

Delete an environment

err := auth.Environments().Delete(ctx, envID)

Deleting an environment permanently removes all users, sessions, organizations, API keys, and audit events associated with it. This cannot be undone. The production and default environments cannot be deleted.

Deactivate / activate

// Suspend an environment -- no authentication operations can complete.
err := auth.Environments().Deactivate(ctx, envID)

// Reactivate a suspended environment.
err := auth.Environments().Activate(ctx, envID)

Deactivating an environment is useful for shutting down a preview environment without deleting its data -- you can reactivate it later.

List environments

environments, err := auth.Environments().List(ctx)

for _, e := range environments {
    fmt.Printf("  %s (type=%s default=%v active=%v)\n",
        e.Name, e.Type, e.IsDefault, e.IsActive)
}

Switching environments in API calls

When making API calls, specify the target environment using the X-Authsome-Environment header or the env query parameter:

POST /api/v1/auth/signin
X-Authsome-Environment: staging

POST /api/v1/auth/signin?env=staging

When neither is provided, the default environment is used.

In Go code, inject the environment ID into the context:

ctx = authsome.WithEnvID(ctx, envID)
// All subsequent auth.* calls use this environment.
user, err := auth.Users().GetByEmail(ctx, "alice@example.com")

HTTP API endpoints

Method	Path	Description
`POST`	`/environments`	Create a new environment
`GET`	`/environments`	List all environments
`GET`	`/environments/:env_id`	Get an environment by ID
`GET`	`/environments/slug/:slug`	Get an environment by slug
`PATCH`	`/environments/:env_id`	Update an environment
`DELETE`	`/environments/:env_id`	Delete an environment
`POST`	`/environments/:env_id/activate`	Activate a suspended environment
`POST`	`/environments/:env_id/deactivate`	Suspend an environment
`POST`	`/environments/:env_id/set-default`	Make an environment the default

Events emitted

Event	Trigger
`environment.created`	A new environment was created
`environment.updated`	Environment settings or details were changed
`environment.deleted`	An environment was permanently deleted
`environment.cloned`	An environment was cloned from another

Environments Overview

On this page