Supabase Auth

https://github.com/supabase/auth
Admin
Supabase Auth is a Go-based authentication and user management server that handles JWT issuance,...
Tokens:216,477
Snippets:1,412
Trust Score:10
License:MIT
Update:7 hours ago
Show doc for...
Tokens:
Raw
### Install GoDotEnv as a library

Source: https://github.com/supabase/auth/blob/master/internal/forks/godotenv/README.md

Use `go get` to install the library for use in your Go project.

```shell
go get github.com/joho/godotenv

```

--------------------------------

### Install GoDotEnv command (go < 1.17)

Source: https://github.com/supabase/auth/blob/master/internal/forks/godotenv/README.md

Use `go get` to install the command-line tool for Go versions before 1.17.

```shell
go get github.com/joho/godotenv/cmd/godotenv

```

--------------------------------

### Install GoDotEnv command (go >= 1.17)

Source: https://github.com/supabase/auth/blob/master/internal/forks/godotenv/README.md

Use `go install` to install the command-line tool for Go 1.17 and later.

```shell
go install github.com/joho/godotenv/cmd/godotenv@latest

```

--------------------------------

### Start Auth

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Starts the Auth executable. It re-runs migrations and then indicates that Auth has started.

```zsh
./auth
```

--------------------------------

### Start development containers with make dev

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Starts the development containers in an attached state with log output. Requires Docker and an .env.docker file configured from example.docker.env.

```bash
make dev
```

--------------------------------

### List users response

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Example response from `GET /admin/users` listing all users.

```json
{
  "aud": "authenticated",
  "users": [
    {
      "id": "b7fd0253-6e16-4d4e-b61b-5943cb1b2102",
      "aud": "authenticated",
      "role": "authenticated",
      "email": "user+4@example.com",
      "phone": "",
      "app_metadata": {
        "provider": "email",
        "providers": ["email"]
      },
      "user_metadata": {},
      "identities": null,
      "created_at": "2021-12-15T12:43:58.12207-05:00",
      "updated_at": "2021-12-15T12:43:58.122073-05:00"
    },
    {
      "id": "d69ae847-99be-4642-868f-439c2cdd9af4",
      "aud": "authenticated",
      "role": "authenticated",
      "email": "user+3@example.com",
      "phone": "",
      "app_metadata": {
        "provider": "email",
        "providers": ["email"]
      },
      "user_metadata": {},
      "identities": null,
      "created_at": "2021-12-15T12:43:56.730209-05:00",
      "updated_at": "2021-12-15T12:43:56.730213-05:00"
    },
    {
      "id": "7282cf42-344e-4474-bdf6-d48e4968a2e4",
      "aud": "authenticated",
      "role": "authenticated",
      "email": "user+2@example.com",
      "phone": "",
      "app_metadata": {
        "provider": "email",
        "providers": ["email"]
      },
      "user_metadata": {},
      "identities": null,
      "created_at": "2021-12-15T12:43:54.867676-05:00",
      "updated_at": "2021-12-15T12:43:54.867679-05:00"
    },
    {
      "id": "e78c512d-68e4-482b-901b-75003e89acae",
      "aud": "authenticated",
      "role": "authenticated",
      "email": "user@example.com",
      "phone": "",
      "app_metadata": {
        "provider": "email",
        "providers": ["email"]
      },
      "user_metadata": {},
      "identities": null,
      "created_at": "2021-12-15T12:40:03.507551-05:00",
      "updated_at": "2021-12-15T12:40:03.507554-05:00"
    }
  ]
}
```

--------------------------------

### Environment file example

Source: https://github.com/supabase/auth/blob/master/_autodocs/configuration.md

Example environment file for configuring the auth service. Includes JWT settings, database connection, and API URLs.

```env
GOTRUE_JWT_SECRET="CHANGE-THIS! VERY IMPORTANT!"
GOTRUE_JWT_EXP="3600"
GOTRUE_JWT_AUD="authenticated"
GOTRUE_JWT_ADMIN_ROLES="supabase_admin,service_role"
DATABASE_URL="postgres://supabase_auth_admin:root@localhost:5432/postgres"
GOTRUE_DB_DRIVER="postgres"
DB_NAMESPACE="auth"
API_EXTERNAL_URL="http://localhost:9999"
PORT="9999"
GOTRUE_SITE_URL="http://localhost:3000"
```

--------------------------------

### Install Go 1.22 with Homebrew

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Installs Go 1.22 via Homebrew on macOS and adds its bin directory to the PATH in ~/.zshrc.

```zsh
# Via Homebrew on macOS
brew install go@1.22

# Set the environment variable in the ~/.zshrc file
echo 'export PATH="/opt/homebrew/opt/go@1.22/bin:$PATH"' >> ~/.zshrc
```

--------------------------------

### Install Docker with Homebrew

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Installs Docker via Homebrew on macOS. Alternatively, Docker Desktop can be downloaded.

```zsh
# Via Homebrew on macOS
brew install docker
```

--------------------------------

### NewAPIWithVersion constructor

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/api.md

Constructor that takes an explicit version string exposed by API.Version() and GET /health. It performs a sequence of setup steps including creating an OIDC provider cache, applying options, setting defaults for captcha verifier, limiter, hooks manager, token service, and mailer, and optionally enabling OAuth server, SCIM, and HIBP pwned client. It also builds the router with middleware and registers routes.

```go
// NewAPIWithVersion creates a new REST API using the specified version
func NewAPIWithVersion(globalConfig *conf.GlobalConfiguration, db *storage.Connection, version string, opt ...Option) *API
```

--------------------------------

### Install Soda CLI with Homebrew

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Installs the Soda CLI via Homebrew on macOS. On macOS Catalina, Brew installation may fail; check GOPATH and run 'go build -o /bin/soda github.com/gobuffalo/pop/soda' to resolve.

```zsh
# Via Homebrew on macOS
brew install gobuffalo/tap/pop
```

--------------------------------

### Example .env file

Source: https://github.com/supabase/auth/blob/master/internal/forks/godotenv/README.md

A sample .env file with key-value pairs for S3_BUCKET and SECRET_KEY.

```shell
S3_BUCKET=YOURS3BUCKET
SECRET_KEY=YOURSECRETKEYGOESHERE

```

--------------------------------

### Install and Activate lefthook Hooks

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Installs lefthook via Homebrew and activates the repo's git hooks from the repo root. This mirrors CI checks locally before each commit.

```zsh
# See https://github.com/evilmartians/lefthook/blob/master/docs/install.md for all install methods
brew install lefthook

# From the repo root, activate the hooks defined in lefthook.yml
make hooks
```

--------------------------------

### POST /passkeys/registration/options

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Get WebAuthn creation options for passkey registration.

```APIDOC
## POST /passkeys/registration/options

### Description
Get WebAuthn creation options for passkey registration.

### Method
POST

### Endpoint
/passkeys/registration/options

### Response
#### Success Response (200)
- **options** (object) - WebAuthn creation options.

#### Response Example
{
  "options": {}
}
```

--------------------------------

### GET /reauthenticate headers

Source: https://github.com/supabase/auth/blob/master/README.md

Example headers for the GET /reauthenticate endpoint. Requires the user to be logged in and have an email or phone number to receive the nonce.

```js
headers: {
  "Authorization" : "Bearer eyJhbGciOiJI...M3A90LCkxxtX9oNP9KZO"
}
```

--------------------------------

### Create user response

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Example response from `POST /admin/users` after creating a user.

```json
{
  "id": "e78c512d-68e4-482b-901b-75003e89acae",
  "aud": "authenticated",
  "role": "authenticated",
  "email": "user@example.com",
  "phone": "",
  "app_metadata": {
    "provider": "email",
    "providers": ["email"]
  },
  "user_metadata": {},
  "identities": null,
  "created_at": "2021-12-15T12:40:03.507551-05:00",
  "updated_at": "2021-12-15T12:40:03.512067-05:00"
}
```

--------------------------------

### Auth startup output

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Expected output after starting Auth, indicating the API is running on localhost:9999.

```zsh
INFO[0000] Auth API started on: localhost:9999
```

--------------------------------

### GET /settings response

Source: https://github.com/supabase/auth/blob/master/README.md

Response from GET /settings. Shows which external OAuth providers are enabled, plus disable_signup and autoconfirm flags.

```json
{
  "external": {
    "apple": true,
    "azure": true,
    "bitbucket": true,
    "discord": true,
    "facebook": true,
    "figma": true,
    "github": true,
    "gitlab": true,
    "google": true,
    "keycloak": true,
    "linkedin": true,
    "notion": true,
    "slack": true,
    "snapchat": true,
    "spotify": true,
    "twitch": true,
    "twitter": true,
    "workos": true
  },
  "disable_signup": false,
  "autoconfirm": false
}
```

--------------------------------

### Example traced HTTP request to /admin/users/{user_id}

Source: https://github.com/supabase/auth/blob/master/README.md

Example HTTP request to the Auth API that is traced. Routes use parametrized versions, and route parameter values appear as http.route.params.<route-key> span attributes.

```http
GET /admin/users/4acde936-82dc-4552-b851-831fb8ce0927/
```

--------------------------------

### GET /settings

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Returns client settings such as enabled providers and feature toggles.

```APIDOC
## GET /settings

### Description
Returns client settings including providers and toggles.

### Method
GET

### Endpoint
/settings

### Response
#### Success Response (200)
- **providers** (array) - List of enabled providers
- **toggles** (object) - Feature toggles
```

--------------------------------

### Run tests in containers with make docker-test

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Starts the containers with a fresh database and runs the project's tests.

```bash
make docker-test
```

--------------------------------

### POST /passkeys/authentication/options

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Get WebAuthn request options for passkey login.

```APIDOC
## POST /passkeys/authentication/options

### Description
Get WebAuthn request options for passkey login.

### Method
POST

### Endpoint
/passkeys/authentication/options

### Response
#### Success Response (200)
- **options** (object) - WebAuthn request options.

#### Response Example
{
  "options": {}
}
```

--------------------------------

### GET /settings

Source: https://github.com/supabase/auth/blob/master/README.md

Retrieves the publicly available settings for the auth instance.

```APIDOC
## GET /settings

### Description
Returns the publicly available settings for this auth instance.

### Method
GET

### Endpoint
/settings

### Response
#### Success Response (200)
- **external** (object) - Object containing booleans for each external provider (e.g., apple, azure, bitbucket, etc.) indicating if they are enabled.
- **disable_signup** (boolean) - Whether signups are disabled.
- **autoconfirm** (boolean) - Whether autoconfirm is enabled.

#### Response Example
{
  "external": {
    "apple": true,
    "azure": true,
    "bitbucket": true,
    "discord": true,
    "facebook": true,
    "figma": true,
    "github": true,
    "gitlab": true,
    "google": true,
    "keycloak": true,
    "linkedin": true,
    "notion": true,
    "slack": true,
    "snapchat": true,
    "spotify": true,
    "twitch": true,
    "twitter": true,
    "workos": true
  },
  "disable_signup": false,
  "autoconfirm": false
}
```

--------------------------------

### GET /verify query params and redirect URL

Source: https://github.com/supabase/auth/blob/master/README.md

Query parameters for GET /verify with type signup, recovery, magiclink, invite, or email_change. The user is logged in and redirected to the SITE_URL with the access token in the fragment. The app should detect the query params in the fragment and use them to set the session (supabase-js does this automatically).

```json
{
  "type": "signup",
  "token": "confirmation-code-delivered-in-email",
  "redirect_to": "https://supabase.io"
}
```

```text
SITE_URL/#access_token=jwt-token-representing-the-user&token_type=bearer&expires_in=3600&refresh_token=a-refresh-token&type=invite
```

--------------------------------

### Settings endpoint response

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Example response from the settings endpoint at `http://localhost:9999/settings`.

```json
{
  "external": {
    "apple": false,
    "azure": false,
    "bitbucket": false,
    "discord": false,
    "github": false,
    "gitlab": false,
    "google": false,
    "facebook": false,
    "snapchat": false,
    "spotify": false,
    "slack": false,
    "slack_oidc": false,
    "twitch": true,
    "twitter": false,
    "email": true,
    "phone": false,
    "saml": false
  },
  "external_labels": {
    "saml": "auth0"
  },
  "disable_signup": false,
  "mailer_autoconfirm": false,
  "phone_autoconfirm": false,
  "sms_provider": "twilio"
}
```

--------------------------------

### GET /scim/v2/ServiceProviderConfig

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Returns the SCIM service provider configuration. Requires `Experimental.ScimEnabled`.

```APIDOC
## GET /scim/v2/ServiceProviderConfig

### Description
Returns the SCIM service provider configuration. Requires `Experimental.ScimEnabled`.

### Method
GET

### Endpoint
/scim/v2/ServiceProviderConfig

### Response
#### Success Response (200)
- (object) - The service provider configuration.

#### Response Example
```json
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "patch": { "supported": true },
  "bulk": { "supported": false }
}
```
```

--------------------------------

### Basic startup with loadGlobalConfig and api.NewAPIWithVersion

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/api.md

Shows the basic startup sequence used by the serve command. It loads the global config, opens the database, creates a mailer template cache and initial rate limiter, then builds the API with NewAPIWithVersion and starts an HTTP server with an atomic handler.

```go
config := loadGlobalConfig(ctx)
db, err := storage.Dial(config)
if err != nil {
	logrus.Fatalf("error opening database: %+v", err)
}
defer db.Close()

// mailer template cache shared between config reloads
mrCache := templatemailer.NewCache()
initialLim := apilimiter.New(config)

api := api.NewAPIWithVersion(
	config, db, utilities.Version,
	api.WithLimiter(initialLim),
	api.WithMailer(templatemailer.FromConfig(config, mrCache)),
)

httpSrv := &http.Server{
	Addr:    net.JoinHostPort(config.API.Host, config.API.Port),
	Handler: reloader.NewAtomicHandler(api),
}
```

```go
fn := func(latestCfg *conf.GlobalConfiguration) {
	latestLim := previousLim.Update(le, latestCfg)

	latestAPI := api.NewAPIWithVersion(
		latestCfg, db, utilities.Version,
		api.WithMailer(templatemailer.FromConfig(latestCfg, mrCache)),
		api.WithLimiter(latestLim),
	)
	ah.Store(latestAPI) // atomically swaps the http.Handler
}
```

--------------------------------

### GET /settings

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/handlers-user.md

Returns the authentication settings, including enabled external providers and global toggles.

```APIDOC
## GET /settings

### Description
Returns the authentication settings, including enabled external providers and global toggles.

### Method
GET

### Endpoint
/settings

### Response
#### Success Response (200)
Returns a Settings object with the following fields:

- **external** (object) - Provider settings with boolean flags for each provider (e.g., anonymous_users, apple, azure, etc.)
- **disable_signup** (boolean) - Whether signup is disabled
- **mailer_autoconfirm** (boolean) - Whether email confirmation is auto-confirmed
- **phone_autoconfirm** (boolean) - Whether phone confirmation is auto-confirmed
- **sms_provider** (string) - The SMS provider
- **saml_enabled** (boolean) - Whether SAML is enabled
- **saml_private_key_next_configured** (boolean) - Whether the SAML private key is configured
- **passkeys_enabled** (boolean) - Whether passkeys are enabled

#### Response Example
{
  "external": {
    "anonymous_users": true,
    "apple": false,
    "azure": false,
    "bitbucket": false,
    "discord": false,
    "facebook": false,
    "snapchat": false,
    "figma": false,
    "fly": false,
    "github": true,
    "gitlab": false,
    "google": true,
    "keycloak": false,
    "kakao": false,
    "linkedin": false,
    "linkedin_oidc": false,
    "notion": false,
    "spotify": false,
    "slack": false,
    "slack_oidc": false,
    "workos": false,
    "twitch": false,
    "twitter": false,
    "email": true,
    "phone": true,
    "zoom": false
  },
  "disable_signup": false,
  "mailer_autoconfirm": true,
  "phone_autoconfirm": false,
  "sms_provider": "twilio",
  "saml_enabled": false,
  "saml_private_key_next_configured": false,
  "passkeys_enabled": false
}
```

--------------------------------

### Set up database and run tests

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Commands to set up a local database and run the test suite. The database is the same one created when installing Auth locally; there is no separate test database.

```sh
# Runs the database in a docker container
$ docker-compose -f docker-compose-dev.yml up postgres

# Applies the migrations to the database (requires soda cli)
$ make migrate_test

# Executes the tests
$ make test
```

--------------------------------

### GET /oauth/authorize

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Starts the authorization code flow. No authentication required; uses cookies and consent.

```APIDOC
## GET /oauth/authorize

### Description
Starts the authorization code flow. No authentication required; uses cookies and consent.

### Method
GET

### Endpoint
/oauth/authorize

### Parameters
#### Query Parameters
- `client_id` (string) - Required - The client identifier.
- `redirect_uri` (string) - Required - The redirect URI.
- `response_type` (string) - Required - Must be `code`.
- `scope` (string) - Optional - The requested scopes.
- `state` (string) - Optional - The state parameter for CSRF protection.

### Response
#### Success Response (302)
- Redirects to the redirect URI with an authorization code or error.

#### Response Example
```
HTTP/1.1 302 Found
Location: https://client.example.com/callback?code=...&state=...
```
```

--------------------------------

### GET /health

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/api.md

HTTP handler for GET /health that returns service availability information.

```APIDOC
## GET /health

### Description
HealthCheck endpoint indicates if the gotrue api service is available.

### Method
GET

### Endpoint
/health

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (200)
- **version** (string) - The version string.
- **name** (string) - The service name.
- **description** (string) - The service description.

#### Response Example
{
  "version": "<version>",
  "name": "GoTrue",
  "description": "GoTrue is a user registration and authentication API"
}
```

--------------------------------

### Run database migrations

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Sets up the database schema via Soda. Successful execution logs 'Auth migrations applied successfully' and lists each applied migration.

```zsh
make migrate_test
```

--------------------------------

### Trace attributes for /admin/users/{user_id} request

Source: https://github.com/supabase/auth/blob/master/README.md

Shows how the example request is traced: http.method, http.route (parametrized), and http.route.params.user_id span attributes.

```text
http.method = GET
http.route = /admin/users/{user_id}
http.route.params.user_id = 4acde936-82dc-4552-b851-831fb8ce0927
```

--------------------------------

### Run auth server with config file and config-dir

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/cmd.md

Starts the auth server using a configuration file and a directory for additional configuration files. The --config flag specifies the main config file, and --config-dir specifies a directory for additional config files.

```bash
./auth --config /etc/gotrue.env --config-dir /etc/gotrue/conf.d serve
```

--------------------------------

### main function in main.go

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/cmd.md

Entry point for the gotrue binary. Sets up embedded migrations, handles OS signals for graceful shutdown, executes the root command with the cancellation context, and waits for observability exporters to clean up.

```go
func main() {
	cmd.EmbeddedMigrations = embeddedMigrations

	execCtx, execCancel := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGHUP, syscall.SIGINT)
	defer execCancel()

	go func() {
		<-execCtx.Done()
		logrus.Info("received graceful shutdown signal")
	}()

	// command is expected to obey the cancellation signal on execCtx and
	// block while it is running
	if err := cmd.RootCommand().ExecuteContext(execCtx); err != nil {
		logrus.WithError(err).Fatal(err)
	}

	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), time.Minute)
	defer shutdownCancel()
	// ... waits for observability exporters (profiler, metrics, traces) cleanup
}
```

--------------------------------

### GET /settings

Source: https://github.com/supabase/auth/blob/master/_autodocs/types.md

Retrieves the current authentication settings, including external provider availability, signup settings, and feature flags.

```APIDOC
## GET /settings

### Description
Returns the current authentication settings, including external provider availability, signup settings, and feature flags.

### Method
GET

### Endpoint
/settings

### Response
#### Success Response (200)
- **external** (ProviderSettings) - Object with boolean flags for each external provider.
- **disable_signup** (boolean) - Whether signup is disabled.
- **mailer_autoconfirm** (boolean) - Whether email confirmation is auto-confirmed.
- **phone_autoconfirm** (boolean) - Whether phone confirmation is auto-confirmed.
- **sms_provider** (string) - The SMS provider in use.
- **saml_enabled** (boolean) - Whether SAML is enabled.
- **saml_private_key_next_configured** (boolean) - Whether the next SAML private key is configured.
- **passkeys_enabled** (boolean) - Whether passkeys are enabled.

#### Response Example
```json
{
  "external": {
    "apple": false,
    "azure": false,
    "bitbucket": false,
    "discord": false,
    "facebook": false,
    "snapchat": false,
    "figma": false,
    "fly": false,
    "github": false,
    "gitlab": false,
    "google": false,
    "keycloak": false,
    "kakao": false,
    "linkedin": false,
    "linkedin_oidc": false,
    "notion": false,
    "spotify": false,
    "slack": false,
    "slack_oidc": false,
    "workos": false,
    "twitch": false,
    "twitter": false,
    "email": false,
    "phone": false,
    "zoom": false,
    "anonymous_users": false
  },
  "disable_signup": false,
  "mailer_autoconfirm": false,
  "phone_autoconfirm": false,
  "sms_provider": "",
  "saml_enabled": false,
  "saml_private_key_next_configured": false,
  "passkeys_enabled": false
}
```
```

--------------------------------

### GET /user response

Source: https://github.com/supabase/auth/blob/master/README.md

Response from GET /user. Returns the JSON object for the logged in user. Requires authentication.

```json
{
  "id": "11111111-2222-3333-4444-5555555555555",
  "email": "email@example.com",
  "confirmation_sent_at": "2016-05-15T20:49:40.882805774-07:00",
  "created_at": "2016-05-15T19:53:12.368652374-07:00",
  "updated_at": "2016-05-15T19:53:12.368652374-07:00"
}
```

--------------------------------

### Load env files by environment convention

Source: https://github.com/supabase/auth/blob/master/internal/forks/godotenv/README.md

Load env files in the recommended order based on the `FOO_ENV` environment variable, with fallback to development.

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

godotenv.Load(".env." + env + ".local")
if "test" != env {
  godotenv.Load(".env.local")
}
godotenv.Load(".env." + env)
godotenv.Load() // The Original .env

```

--------------------------------

### HealthCheck JSON response example

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/api.md

Example JSON response from the HealthCheck endpoint, showing the version, name, and description fields.

```json
{
  "version": "<version>",
  "name": "GoTrue",
  "description": "GoTrue is a user registration and authentication API"
}
```

--------------------------------

### NewService constructor

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/tokens.md

Creates a new Service instance.

```go
// NewService creates a new Service
func NewService(config *conf.GlobalConfiguration, hookManager HookManager) *Service {
	return &Service{
		config:      config,
		hookManager: hookManager,
		now:         time.Now,
	}
}
```

--------------------------------

### Usage example: FindUserByEmailAndAudience and Authenticate

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/models-user.md

Shows how to retrieve a user by email and audience, handle not-found errors, check email confirmation, and authenticate with password. Uses storage.Connection and config for DB encryption.

```go
user, err := models.FindUserByEmailAndAudience(db, "user@example.com", "authenticated")
if err != nil {
	if models.IsNotFoundError(err) {
		// 400 invalid_credentials handled at the API layer
	}
}

if !user.IsConfirmed() {
	// ask user to verify email first
}

valid, shouldReEncrypt, err := user.Authenticate(ctx, db, password,
	config.Security.DBEncryption.DecryptionKeys,
	config.Security.DBEncryption.Encrypt,
	config.Security.DBEncryption.EncryptionKeyID)
```

--------------------------------

### POST /signup

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/handlers-auth-flows.md

Creates a new user account with email and password, optionally including metadata and PKCE code challenge for OAuth flows.

```APIDOC
## POST /signup

### Description
Creates a new user account with email and password, optionally including metadata and PKCE code challenge for OAuth flows.

### Method
POST

### Endpoint
/signup

### Parameters
#### Request Body
- **email** (string) - Required - User's email address.
- **password** (string) - Required - User's password.
- **data** (object) - Optional - Additional user metadata.
- **code_challenge** (string) - Optional - PKCE code challenge.
- **code_challenge_method** (string) - Optional - PKCE code challenge method (e.g., 's256').

### Request Example
{
  "email": "ada@example.com",
  "password": "correct horse battery staple",
  "data": {"first_name": "Ada"},
  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "code_challenge_method": "s256"
}

### Response
#### Success Response (200)
No response body documented.

#### Response Example
No response example provided.

```

--------------------------------

### GET /verify

Source: https://github.com/supabase/auth/blob/master/README.md

Verifies a registration or password recovery token via GET request, redirecting the user with the access token in the URL fragment.

```APIDOC
## GET /verify

### Description
Verify a registration or a password recovery. The type can be `signup`, `recovery`, `magiclink`, `invite`, or `email_change` and the token is a token returned from either `/signup`, `/recover`, or `/magiclink`. The user will be logged in and redirected to the site URL with the access token in the fragment.

### Method
GET

### Endpoint
/verify

### Parameters
#### Query Parameters
- **type** (string) - Required - The type of verification: `signup`, `recovery`, `magiclink`, `invite`, or `email_change`.
- **token** (string) - Required - The token returned from `/signup`, `/recover`, or `/magiclink`.
- **redirect_to** (string) - Optional - URL to redirect to after verification.

### Request Example
```json
{
  "type": "signup",
  "token": "confirmation-code-delivered-in-email",
  "redirect_to": "https://supabase.io"
}
```

### Response
#### Success Response (200)
The user is logged in and redirected to `SITE_URL/#access_token=jwt-token-representing-the-user&token_type=bearer&expires_in=3600&refresh_token=a-refresh-token&type=invite`. The app should detect the query params in the fragment and use them to set the session.

#### Response Example
```
SITE_URL/#access_token=jwt-token-representing-the-user&token_type=bearer&expires_in=3600&refresh_token=a-refresh-token&type=invite
```
```

--------------------------------

### Build output for `make build`

Source: https://github.com/supabase/auth/blob/master/README.md

Output shown after running `make build` in the Quick Start section. It builds the auth binary for the current platform and for linux/arm64, embedding the current git commit hash into the version variable.

```bash
go build -ldflags "-X github.com/supabase/auth/cmd.Version=`git rev-parse HEAD`"
GOOS=linux GOARCH=arm64 go build -ldflags "-X github.com/supabase/auth/cmd.Version=`git rev-parse HEAD`" -o gotrue-arm64
```

--------------------------------

### Hook rejection example with curl

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/hooks.md

Example of a password verification attempt that is rejected by a hook. The client receives a 400 response with the error code 'invalid_credentials' and a message from the hook output.

```bash
curl -X POST http://localhost:9999/token -d 'grant_type=password&email=u@example.com&password=pw'
# 400 {"code":"invalid_credentials","msg":"Blocked by security policy"}  (message from hook output)
```

--------------------------------

### POST /verify

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/handlers-auth-flows.md

Exchanges a confirmation or recovery token for a refresh token. Supports both GET and POST requests, with GET requiring a token or token_hash, and POST requiring exactly one of token or token_hash.

```APIDOC
## [POST] /verify

### Description
Exchanges a confirmation or recovery token for a refresh token. Supports both GET and POST requests, with GET requiring a token or token_hash, and POST requiring exactly one of token or token_hash.

### Method
POST

### Endpoint
/verify

### Parameters
#### Request Body
- **type** (string) - Required - The type of verification: signup, invite, recovery, magiclink, email_change, email_change_current, email_change_new, phone_change, reauthentication, sms, phone_change.
- **token** (string) - Optional - The verification token. Required if token_hash is not provided.
- **token_hash** (string) - Optional - The hash of the verification token. Required if token is not provided.
- **email** (string) - Optional - The email address associated with the verification.
- **phone** (string) - Optional - The phone number associated with the verification.
- **redirect_to** (string) - Optional - The redirect URL for PKCE flows.

### Request Example
{
  "type": "signup",
  "token": "example-token",
  "email": "user@example.com"
}

### Response
#### Success Response (200)
Returns an AccessTokenResponse. In PKCE flows, the refresh token is withheld and a redirect to the code exchange is used.

#### Response Example
{
  "access_token": "example-access-token",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "example-refresh-token"
}
```

--------------------------------

### POST /signup

Source: https://github.com/supabase/auth/blob/master/_autodocs/types.md

Creates a new user account with the provided parameters.

```APIDOC
## POST /signup

### Description
Creates a new user account with the provided parameters.

### Method
POST

### Endpoint
/signup

### Parameters
#### Request Body
- **SignupParams** (object) - The signup request parameters. See the handler page for field details.

### Response
#### Success Response (200)
- **User** (object) - The created user object.

#### Response Example
```json
{
  "id": "uuid",
  "email": "user@example.com",
  "created_at": "timestamp"
}
```
```

--------------------------------

### GET /admin/oauth/clients

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Lists all OAuth clients.

```APIDOC
## GET /admin/oauth/clients

### Description
Lists all OAuth clients.

### Method
GET

### Endpoint
/admin/oauth/clients

### Response
#### Success Response (200)
Returns a list of OAuth clients.
```

--------------------------------

### GET /admin/sso/providers

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/handlers-admin.md

Lists all SSO providers.

```APIDOC
## GET /admin/sso/providers

### Description
Lists all SSO providers configured for the admin.

### Method
GET

### Endpoint
/admin/sso/providers

### Response
#### Success Response (200)
- Returns a list of SSO provider objects.
```

--------------------------------

### Configure database driver and connection URL

Source: https://github.com/supabase/auth/blob/master/README.md

Sets the database driver (must be postgres) and the connection string. Both are required.

```properties
GOTRUE_DB_DRIVER=postgres
DATABASE_URL=root@localhost/auth
```

--------------------------------

### Build Auth binary

Source: https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

Compiles the Auth binary. Run this after fetching the tags from the upstream repository.

```zsh
make build
```

--------------------------------

### GET /admin/sso/providers

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Lists all SAML SSO providers.

```APIDOC
## GET /admin/sso/providers

### Description
Lists all SAML SSO providers.

### Method
GET

### Endpoint
/admin/sso/providers

### Response
#### Success Response (200)
Returns a list of SSO providers.
```

--------------------------------

### GET /admin/users/{user_id}

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Retrieves a user by ID.

```APIDOC
## GET /admin/users/{user_id}

### Description
Retrieves a user by ID.

### Method
GET

### Endpoint
/admin/users/{user_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The user ID.

### Response
#### Success Response (200)
Returns the user object.
```

--------------------------------

### Autoload .env on import

Source: https://github.com/supabase/auth/blob/master/internal/forks/godotenv/README.md

Import the autoload package to automatically load .env from the project root on import.

```go
import _ "github.com/joho/godotenv/autoload"

```

--------------------------------

### GET /admin/audit

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Retrieves the audit log entries.

```APIDOC
## GET /admin/audit

### Description
Retrieves the audit log entries.

### Method
GET

### Endpoint
/admin/audit

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number.
- **per_page** (integer) - Optional - Number of entries per page.
- **query** (string) - Optional - Query in the format `<scope>:<value>`.
```

--------------------------------

### Apply database migrations

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/cmd.md

Runs database migrations for the auth server.

```bash
./auth migrate
```

--------------------------------

### GET /passkeys

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

List all passkeys for the current user.

```APIDOC
## GET /passkeys

### Description
List all passkeys for the current user.

### Method
GET

### Endpoint
/passkeys

### Response
#### Success Response (200)
- **passkeys** (array of objects) - The list of passkeys.

#### Response Example
{
  "passkeys": []
}
```

--------------------------------

### GET /admin/oauth/clients/{client_id}

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Retrieves an OAuth client by ID.

```APIDOC
## GET /admin/oauth/clients/{client_id}

### Description
Retrieves an OAuth client by ID.

### Method
GET

### Endpoint
/admin/oauth/clients/{client_id}

### Parameters
#### Path Parameters
- **client_id** (string) - Required - The client ID.

### Response
#### Success Response (200)
Returns the client details.
```

--------------------------------

### GET /admin/users/{user_id}/passkeys

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Lists the passkeys for a user.

```APIDOC
## GET /admin/users/{user_id}/passkeys

### Description
Lists the passkeys for a user.

### Method
GET

### Endpoint
/admin/users/{user_id}/passkeys

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The user ID.

### Response
#### Success Response (200)
Returns a list of passkeys.
```

--------------------------------

### Signup and verify with curl

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/handlers-auth-flows.md

These curl commands demonstrate the signup and verify endpoints. The signup request includes PKCE parameters (code_challenge and code_challenge_method) and user metadata. The verify request exchanges the magic link token for a session.

```bash
curl -X POST http://localhost:9999/signup \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "ada@example.com",
    "password": "correct horse battery staple",
    "data": {"first_name": "Ada"},
    "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
    "code_challenge_method": "s256"
  }'
```

```bash
# exchange the magic link token for a session
curl -X POST http://localhost:9999/verify \
  -H 'Content-Type: application/json' \
  -d '{"type":"magiclink","token_hash":"<token_hash from email>","email":"ada@example.com"}'
```

--------------------------------

### POST /signup

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/handlers-auth-flows.md

Registers a new user with email/phone and password, or anonymously when email and phone are empty. Handles confirmation flows, PKCE, and returns an access token or user object.

```APIDOC
## POST /signup

### Description
Registers a new user with email/phone and password, or anonymously when email and phone are empty. Handles confirmation flows, PKCE, and returns an access token or user object.

### Method
POST

### Endpoint
/signup

### Parameters
#### Request Body
- **email** (string) - Optional (one of email/phone) - Email address
- **phone** (string) - Optional (one of email/phone) - E.164 phone number
- **password** (string) - Required - Must pass strength checks (length, required chars, HIBP)
- **data** (object) - Optional - `user_metadata` payload
- **channel** (string) - Optional - `sms`/`whatsapp` for phone signups
- **code_challenge_method** (string) - Optional - `s256` (or `plain`)
- **code_challenge** (string) - Optional - PKCE challenge (email signup only)

### Request Example
```json
{
  "email": "user@example.com",
  "password": "strongpassword",
  "data": {"name": "John"},
  "code_challenge_method": "s256",
  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
}
```

### Response
#### Success Response (200)
Returns an `AccessTokenResponse` or the `User` object.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "user": {
    "id": "...",
    "email": "user@example.com",
    "app_metadata": {"provider": "email"}
  }
}
```

### Error Handling
- **422** - `ErrorCodeAnonymousProviderDisabled` - "Anonymous sign-ins are disabled" (when anonymous signup is disabled)
- **400** - Invalid parameters (empty password, weak password, both email+phone, invalid channel, PKCE with phone, malformed PKCE params)
```

--------------------------------

### GET /reauthenticate

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Sends a reauthentication OTP to the current user.

```APIDOC
## GET /reauthenticate

### Description
Sends a reauthentication OTP to the current user.

### Method
GET

### Endpoint
/reauthenticate

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
{
  "message": "Reauthentication OTP sent."
}
```

--------------------------------

### GET /admin/users/{user_id}

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/handlers-admin.md

Retrieves a single user by ID.

```APIDOC
## GET /admin/users/{user_id}

### Description
Retrieves a single user by ID.

### Method
GET

### Endpoint
/admin/users/{user_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The user ID (UUID).

### Response
#### Success Response (200)
- **User object** - The requested user.

#### Response Example
```json
{
  "id": "uuid",
  "email": "user@example.com"
}
```

### Error Handling
- Non-UUID `user_id` returns `ErrorCodeValidationFailed` (404).
- Missing user returns `ErrorCodeUserNotFound` (404).
```

--------------------------------

### GET /admin/custom-providers/{identifier}

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Retrieves a custom OAuth provider by identifier.

```APIDOC
## GET /admin/custom-providers/{identifier}

### Description
Retrieves a custom OAuth provider by identifier.

### Method
GET

### Endpoint
/admin/custom-providers/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The provider identifier.

### Response
#### Success Response (200)
Returns the provider details.
```

--------------------------------

### Configure dual-key window with GOTRUE_SAML_PRIVATE_KEY_NEXT

Source: https://github.com/supabase/auth/blob/master/docs/saml_key_rotation.md

Sets the new key as the next key without changing the primary key. After redeploying, both certificates appear in metadata, cache-control drops to max-age=60, and the /settings endpoint reports saml_private_key_next_configured as true. If encrypted assertions are enabled, both certificates also appear as encryption descriptors and decryption retries with the old key.

```plaintext
GOTRUE_SAML_PRIVATE_KEY=<current key — unchanged>
GOTRUE_SAML_PRIVATE_KEY_NEXT=<new key from Step 1>
```

--------------------------------

### Define serve command with cobra

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/cmd.md

Defines the `serve` command using cobra, with a Run function that calls `serve(cmd.Context())`. The actual server logic is in the `serve` function.

```go
var serveCmd = cobra.Command{
	Use:  "serve",
	Long: "Start API server",
	Run: func(cmd *cobra.Command, args []string) {
		serve(cmd.Context())
	},
}

func serve(ctx context.Context) { ... }
```

--------------------------------

### GET /admin/sso/providers/{idp_id}

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Retrieves a SAML SSO provider by ID.

```APIDOC
## GET /admin/sso/providers/{idp_id}

### Description
Retrieves a SAML SSO provider by ID.

### Method
GET

### Endpoint
/admin/sso/providers/{idp_id}

### Parameters
#### Path Parameters
- **idp_id** (string) - Required - The provider ID.

### Response
#### Success Response (200)
Returns the provider details.
```

--------------------------------

### NewBitbucketProvider

Source: https://github.com/supabase/auth/blob/master/_autodocs/api-reference/provider.md

Creates a Bitbucket OAuth provider.

```APIDOC
## NewBitbucketProvider

### Description
Creates a Bitbucket OAuth provider.

### Signature
`NewBitbucketProvider(ext conf.OAuthProviderConfiguration) (OAuthProvider, error)`

### Parameters
- **ext** (conf.OAuthProviderConfiguration) - Required - OAuth provider configuration.

### Returns
- **OAuthProvider** - The created provider.
- **error** - Error if validation fails.
```

--------------------------------

### GET /factors/recovery-codes

Source: https://github.com/supabase/auth/blob/master/_autodocs/endpoints.md

Check the status of recovery codes for the current user.

```APIDOC
## GET /factors/recovery-codes

### Description
Check the status of recovery codes for the current user.

### Method
GET

### Endpoint
/factors/recovery-codes

### Response
#### Success Response (200)
- **status** (string) - The status of the recovery codes (e.g., `active`, `not_generated`).

#### Response Example
{
  "status": "active"
}
```
Tokens:
Raw