Supabase Auth

Supabase Auth follows Semantic Versioning. Note that Auth is not intended to be used as a Go library; there are no guarantees on backward API compatibility when used as a library.

Patch Versions

Guarantees include:

• Database objects (tables, columns, indexes, functions).
• REST API.
• JWT structure.
• Configuration.

Note: Tables may add new columns, and JWTs may add new properties.

Minor Versions

Guarantees include:

• REST API.
• JWT structure.
• Configuration.

Note: Deprecated APIs or configurations may continue to work for a few releases. Significant schema changes or removal of JWT fields after deprecation are not guaranteed.

Major Versions

• No backward compatibility is guaranteed.

The following features from the original Netlify GoTrue codebase are not supported by Supabase Auth and may be removed without notice:

• Multi-tenancy via the instances table (GOTRUE_MULTI_INSTANCE_MODE).
• System user (zero UUID user).
• Super admin via the is_super_admin column.
• Group information in JWTs via GOTRUE_JWT_ADMIN_GROUP_NAME and other configuration fields.
• HS256 JWT signing (Asymmetric keys like RS256 are the default; HS256 is supported for compatibility but migration to asymmetric keys is recommended).

By default, existing environment variables take precedence over those loaded from a .env file. If you want to overwrite existing variables, use godotenv.Overload().

A common pattern for managing multiple environments (development, test, production) is to use an environment variable like FOO_ENV to determine which .env file to load in a specific order.

env := os.Getenv("FOO_ENV")
if "" == env {
  env = "development"
}

// Loading order pattern:
// 1. Load environment-specific local overrides
godotenv.Load(".env." + env + ".local")
// 2. Load general local overrides (if not in test)
if "test" != env {
  godotenv.Load(".env.local")
}
// 3. Load environment-specific config
godotenv.Load(".env." + env)
// 4. Load the base .env file
godotenv.Load()

To run the entire Supabase Auth stack using Docker, follow these steps:

1. Create a .env.docker file for your environment variables. Use example.docker.env as a template.
2. Build the project: make build
3. Start the development environment: make dev
4. Verify that two containers are running (auth-auth-1 and auth-postgres-1) using docker ps.
5. Confirm the service is running by visiting the health check endpoint: http://localhost:9999/health

make build
make dev
docker ps
# Visit http://localhost:9999/health to confirm

To load variables from a .env file into your process's environment, use godotenv.Load(). By default, it looks for a file named .env in the current directory. You can also specify custom filenames or multiple files.

Alternatively, you can use the autoload package to automatically load .env on import without calling Load() explicitly.

package main

import (
    "log"
    "os"

    "github.com/joho/godotenv"
)

func main() {
  // Loads .env from the current directory
  err := godotenv.Load()
  if err != nil {
    log.Fatal("Error loading .env file")
  }

  s3Bucket := os.Getenv("S3_BUCKET")
  secretKey := os.Getenv("SECRET_KEY")
}

You can install GoDotEnv either as a Go library for your application or as a standalone binary command.

As a library

Use go get to add it to your project dependencies.

As a binary command

If you are using Go >= 1.17, use go install. For older versions, use go get.

To run Supabase Auth locally using a standalone Postgres container, follow these steps:

1. Create a .env file to store your custom environment variables. You can use example.env as a template.
2. Start the local Postgres database: docker-compose -f docker-compose-dev.yml up postgres
3. Build the auth binary: make build
4. Execute the binary: ./auth

When self-hosting Supabase Auth, follow these best practices to ensure stability and backward compatibility:

1. Do not modify the schema managed by Auth. Refer to the migrations directory to see the managed schema.
2. Do not rely on the database schema or data structure. Always use the provided Auth APIs and JWTs to retrieve user information.
3. Always run Auth behind a TLS-capable proxy (e.g., a load balancer, CDN, or Nginx).

Settings for connecting to the underlying database.

• GOTRUE_DB_DRIVER (required): Must be postgres.
• DATABASE_URL or DB_DATABASE_URL (required): The connection string.
• GOTRUE_DB_MAX_POOL_SIZE: Maximum open connections (defaults to 0/unlimited).
• DB_NAMESPACE: A prefix added to all table names.

Migrations: Migrations run automatically on startup. To run them manually:

• Locally: ./auth migrate
• Docker: docker run --rm auth gotrue migrate

GOTRUE_DB_DRIVER=postgres
DATABASE_URL=root@localhost/auth

The IdentitySchema represents an identity linked to a user via an external provider (e.g., Google, GitHub).

Key fields:

• Id: The unique identity ID.
• UserId: The ID of the user this identity belongs to.
• Provider: The name of the provider.
• Email: The email associated with this identity.
• IdentityData: A map containing provider-specific data.