{"id":17806193,"url":"https://github.com/jrapoport/gothic","last_synced_at":"2025-04-09T19:19:47.685Z","repository":{"id":44694383,"uuid":"322422699","full_name":"jrapoport/gothic","owner":"jrapoport","description":"🦇 Gothic is a user registration and authentication SWT/JWT microservice. It supports REST, gRPC, and gRPC Web API, reCAPTCHA \u0026 a variety of DBs with Gorm.","archived":false,"fork":false,"pushed_at":"2025-03-13T01:20:57.000Z","size":17772,"stargazers_count":77,"open_issues_count":2,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-09T19:19:32.485Z","etag":null,"topics":["authorization","go","gorm","goth","grpc","grpc-api","grpc-web","jwt","mysql","postgres","recaptcha","rest","restful","restful-api","signup","smtp","sqlite","sqlserver","swt","usermanagement"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jrapoport.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-17T21:58:36.000Z","updated_at":"2025-02-06T14:46:51.000Z","dependencies_parsed_at":"2024-11-15T08:37:54.942Z","dependency_job_id":null,"html_url":"https://github.com/jrapoport/gothic","commit_stats":{"total_commits":112,"total_committers":1,"mean_commits":112.0,"dds":0.0,"last_synced_commit":"4a19e6c3579b50f8421ddee1ebd9c6f7126b401b"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrapoport%2Fgothic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrapoport%2Fgothic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrapoport%2Fgothic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrapoport%2Fgothic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jrapoport","download_url":"https://codeload.github.com/jrapoport/gothic/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248094991,"owners_count":21046770,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authorization","go","gorm","goth","grpc","grpc-api","grpc-web","jwt","mysql","postgres","recaptcha","rest","restful","restful-api","signup","smtp","sqlite","sqlserver","swt","usermanagement"],"created_at":"2024-10-27T13:04:38.809Z","updated_at":"2025-04-09T19:19:47.661Z","avatar_url":"https://github.com/jrapoport.png","language":"Go","funding_links":["https://www.buymeacoffee.com/jrapoport"],"categories":["Go"],"sub_categories":[],"readme":"# 🦇 \u0026nbsp;Gothic\n\n![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/jrapoport/gothic/test.yaml?branch=master\u0026style=flat-square)\n[![Go Report Card](https://goreportcard.com/badge/github.com/jrapoport/gothic?style=flat-square\u0026)](https://goreportcard.com/report/github.com/jrapoport/gothic)\n[![Codecov](https://img.shields.io/codecov/c/github/jrapoport/gothic?style=flat-square)](https://codecov.io/gh/jrapoport/gothic)\n![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/jrapoport/gothic?style=flat-square)\n[![GitHub](https://img.shields.io/github/license/jrapoport/gothic?style=flat-square)](https://github.com/jrapoport/gothic/blob/master/LICENSE)\n\n[![Buy Me A Coffee](https://img.shields.io/badge/buy%20me%20a%20coffee-☕-6F4E37?style=flat-square)](https://www.buymeacoffee.com/jrapoport)\n\nGothic is a user registration and authentication microservice written in Go. It's based on OAuth2 and JWT and will\nhandle user signup, authentication and custom user data.\n\n## WHY?\n\n`Gothic` is a free production-ready authentication server.\n\nIt is a complete rewrite of [Netlify's GoTrue](https://github.com/netlify/gotrue) and is ~85-90% complete.\n\n`GoTrue` only supports `REST` + `mysql`, and is outdated. `Auth0` is prohibitively expensive for small startups, \ngarage projects, \u0026 consumer applications.\n\n`Gothic` is designed to get you up and running quickly without having to spend months coding the exact same thing for the \numpteenth time —  without sacrificing functionality, or a professional look \u0026 feel.\n\n**UPDATE**  \n* Docker containers now build and compose correctly on Apple Silicon (arm64).\n\n\n* REST API is now complete w.r.t. GoTrue's functionality (except for SAML — which was intentionally left out).\n  \n\n* gRPC API is now (95%) complete w.r.t. GoTrue's functionality.\n\n## WIP\n\nThis project is currently in progress. Things *will* change. Sometimes big things. Don't @ me.\n\n## Getting Started\n\n### Installing\n\nTo start using Gothic, install Go (version 1.15+) and run `go get`:\n\n```sh\n$ go get -u github.com/jrapoport/gothic\n```\n\n### Building\n\nGothic supports GO Modules. To build Gothic simply type `make` or `make build` after cloning this repo to build a\n`DEBUG` version of Gothic for development. This will build `gothic` \u0026 its command line tool, `gadmin`, under the `build`\ndirectory.\n\n```sh\n$ make\n# or \n$ make build\n```\n\nTo build a `RELEASE` (a.k.a. production) version of Gothic use `make release`\n\n```sh\n$ make release\n```\n\n### Running\n\nGothic supports configuration through environment vars, `.env` files, `.json` files or `.yaml` and only requires a\nhandful of configuration options to get started.\n\nFor a full list of configuration options please see the [Configuration](#configuration) section below.\n\n### Using Gadmin\n\nGadmin is the Gothic control plane.\n\n#### Building Gadmin \n\n```sh\n$ make\n# or \n$ make build\n```\n\nTo build a `RELEASE` (a.k.a. production) version of Gadmin use `make release`\n\nGAdmin requires the address of your Gothic rpc admin server \u0026 your root password. The address and password can be \nsupplied in a [configuration file](#configuration) by setting a path to the file with `-c` (or `--config`) command line \nswitch. Alternatively you can set the server address with the `-s` (`--server`) switch and the root password using the \n`--root` switch.\n\n#### Generating a signup code with Gadmin\n\nFirst make sure that Gothic is up and running and that its admin server is accessible.\n\n```sh\n$ ./build/release/gadmin -s [ADMIN_SERVER_ADDRESS] --root [ROOT_PASSWORD] code\n\u003e created 1 codes\n\u003e 123456\n```\n\n### Using gRPC-Web\n\nFirst start your instance of `gothic`, or use the container:\n\n```sh\n$ make db\n$ make gothic\n```\n\nNext, you will need to start the `envoy` server\n\n```sh\n$ make envoy\n```\n\nOnce `gothic`, the db, \u0026 `envoy` are running you can make gRPC-Web calls using\nthe [javascript bindings](https://github.com/jrapoport/gothic/blob/master/api/grpc/web).\n\nto regenerate the protobuf typescript bindings:\n\n```sh\n$ make rpcw\n# or\n$ make grpc\n```\n\n#### Startup\n\nBy default, Gothic will search a config file named `gothic.env`, `gothic.json`, or `gothic.yaml` in the following\ndirectory locations:\n\n```sh\n$ .\n$ ~/.gothic\n$ /etc/gothic\n```\n\nAlternatively, you can use the `--config` or `-c` command line flag to specify a path to a config file to use.\n\n#### Required Settings\n\n```properties\nGOTHIC_SITE_URL=http://example.com\nGOTHIC_ROOT_PASSWORD=my-super-admin-password\nGOTHIC_JWT_SECRET=i-am-a-secret\nGOTHIC_DB_DRIVER=mysql\nGOTHIC_DB_DSN=root@tcp(localhost:3306)/my_gothic_db\n```\n\n`GOTHIC_SITE_URL` - `string` **required**\n\nThis is base URL for your site. The base url is used to construct things like referral URLs in email.\n\n`GOTHIC_ROOT_PASSWORD` - `string` **required**\n\nThe password for the built-in super admin account. Certain operations are currently restricted to the super admin user.\n\nInteractive logins are **not** supported for super admins and super admin functionality must be accessed via `gadmin`.\n*This may change in the future with additional API support for the root password a/o a specialized bearer token.*\n\n`GOTHIC_JWT_SECRET` - `string` **required**\n\nThe shared secret for JWT tokens. Webhooks can optionally override this with a custom value for callbacks.\n\n```properties\nGOTHIC_DB_DRIVER=mysql\nGOTHIC_DB_DSN=root@tcp(0.0.0.0:3306)/my_gothic_db\n```\n\n`GOTHIC_DB_DRIVER` - `string` **required**\n\nThe dialect of the database you to use. Currently, `mysql`, `postgres`, `sqlserver`, and `sqlite` (or `sqlite3`) are all\nsupported. Other values will be treated as a generic sql connection and passed to the `mysql` driver.  \nDefaults to `mysql`.\n\nIn the future, direct support for other databases via `gorm.io` drivers may be added.\n\n`GOTHIC_DB_DSN` - `string` **required**\n\nConnection string for the database.\n\n## Supported Technologies\n\n### gRPC \u0026 gRPC-Web APIs\n\nGothic supports a full range of gRPC \u0026 gRPC-Web APIs. gRPC-Web APIs are external and designed to be publicly available.\nBy contrast, gRPC APIs are reserved for admin operations a/o microservice communication. The gRPC host address should\n**not** be publicly accessible.\n\n**API are currently a WIP**. For now, they should not be considered stable and subject to change at any time.\n\n### REST APIs\n\nGothic supports a full range of REST APIs for users \u0026 administrative access.\n\n**API are currently a WIP**. For now, they should not be considered stable and subject to change at any time.\n\n### Databases\n\nGothic uses [gorm](https://gorm.io/) for database support.\n\n### OAuth External Providers\n\nGothic uses [goth](https://github.com/markbates/goth) for external oauth providers now. Now we support everything\nthat [goth](https://github.com/markbates/goth) supports.\n\n### Email Formatting\n\nGothic uses [hermes](https://github.com/matcornic/hermes/) for email templates.\n\n### SMTP\n\nGothic uses [go-simple-mail](https://github.com/xhit/go-simple-mail/) for smtp server support.\n\n### JWT Tokens\n\nGothic uses [lestrrat-go](https://github.com/lestrrat-go/jwx) for jwt tokens.\n\n### Config Files\n\nGothic uses [viper](https://github.com/spf13/viper) for configuration file support.\n\n### CLI\n\nGothic uses [cobra](https://github.com/spf13/cobra) for command line tool support.\n\n## Configuration\n\nGothic supports config files in `.env`, `.yaml` and `.json` formats in addition to env vars.\n\nPlease see the [example.env](https://github.com/jrapoport/gothic/blob/master/example.env) or\n[test configurations](https://github.com/jrapoport/gothic/blob/master/config/testdata) for complete examples.\n\n### Service\n\n```properties\nGOTHIC_SERVICE=\"gothic\"\nGOTHIC_SITE_URL=http://example.com\n```\n\n`GOTHIC_SERVICE` - `string`\n\nThe name of the authentication service. This is used in a variety of places and settings. A normalized version of this\nvalue is also used as the name of the internal (email) signup provider (enabled by default). Defaults to `gothic`.\n\n`GOTHIC_SITE_URL` - `string` **required**\n\nThis is base URL for your site. The base url is used to construct things like referral URLs in email.\n\n### Networking\n\n```properties\nGOTHIC_HOST=localhost\nGOTHIC_HEALTH_ADDRESS=localhost:7720\nGOTHIC_RPC_ADDRESS=localhost:7721\nGOTHIC_ADMIN_ADDRESS=localhost:7722\nGOTHIC_REST_ADDRESS=localhost:7727\nGOTHIC_RPCWEB_ADDRESS=localhost:7729\nGOTHIC_REQUEST_ID=gothic-req\n```\n\n`GOTHIC_HOST` - `string`\n\nHostname to listen on. Defaults to `localhost`.\n\n`GOTHIC_HEALTH_ADDRESS` - `string`\n\nThe health check host address to listen on. The health check host currently uses `HTTP` and responds to any `GET`\nrequest with a `json` response. Defaults to `[GOTHIC_HOST]:7720`.\n\n`GOTHIC_RPC_ADDRESS` - `string`\n\nThe gRPC host address to listen on. gRPC APIs are for admin operations a/o microservice communication. Defaults to\n`[GOTHIC_HOST]:7721`.\n\nThe gRPC API should be considered internal and **not** publicly available. This address should **not** be internet\naccessible.\n\n`GOTHIC_ADMIN_ADDRESS` - `string`\n\nThe gRPC admin host address to listen on. Operations on this address are secured by a valid JWT token with admin \npermissions. Defaults to `[GOTHIC_HOST]:7722`.\n\n`GOTHIC_REST_ADDRESS` - `string`\n\nThe REST host address to listen on. REST APIs are for users \u0026 administrative access. Defaults to `[GOTHIC_HOST]:7727`.\n\nThe REST API should be considered external and publicly available. This address should be internet accessible.\n\n`GOTHIC_RPCWEB_ADDRESS` - `string`\n\nThe gRPC-Web host address to listen on. gRPC-Web APIs are for users \u0026 (potentially some) administrative access. Defaults\nto `[GOTHIC_HOST]:7729`.\n\nThe gRPC-Web API should be considered external and publicly available. This address *could* be internet accessible for\ndirect gGPC HTTP/2 communication. However, typically this address would **not** be internet accessible. Instead, it\nwould be accessible to an [Envoy](https://www.envoyproxy.io/) proxy server, which would itself expose an internet\naccessible address. Please see [envoy.yaml](https://github.com/jrapoport/gothic/blob/master/envoy.yaml) \u0026\n[docker-compose.yaml](https://github.com/jrapoport/gothic/blob/master/docker-compose.yaml) for a working example.\n\nFor more details on the `envoy` proxy, please see [https://www.envoyproxy.io/](https://www.envoyproxy.io/).\n\n`GOTHIC_REQUEST_ID` - `string` **in progress**\n\nThe prefix of the request id to use. Support for request ids / a request id prefix is in progress.\n\n### Security\n\n```properties\n# general\nGOTHIC_ROOT_PASSWORD=my-super-admin-password\nGOTHIC_MASK_EMAILS=true\nGOTHIC_RATE_LIMIT=5m0s\n# jwt\nGOTHIC_JWT_SECRET=i-am-a-secret\nGOTHIC_JWT_ALGORITHM=HS256\nGOTHIC_JWT_ISSUER=gothic\nGOTHIC_JWT_AUDIENCE=gothic-server-01\nGOTHIC_JWT_EXPIRATION=60m0s\n# recaptcha\nGOTHIC_RECAPTCHA_KEY=SECRET-RECAPTCHA-KEY\nGOTHIC_RECAPTCHA_LOGIN=true\n# validation\nGOTHIC_VALIDATION_USERNAME_REGEX=\"^[a-zA-Z0-9_]{2,255}$\"\nGOTHIC_VALIDATION_PASSWORD_REGEX=\"^[a-zA-Z0-9[:punct:]]{8,40}$\"\n# cookies\nGOTHIC_COOKIES_DURATION=24h0m0s\n```\n\n#### General\n\n`GOTHIC_ROOT_PASSWORD` - `string` **required**\n\nThe password for the built-in super admin account. Certain operations are currently restricted to the super admin user.\n\n`GOTHIC_MASK_EMAILS` - `boolean (\"true\" or \"false\")`\n\nIf `true` Gothic will automatically mask the users email when returning user information by default. Please note that\nadmin requests for user info will **always** return **unmasked** emails. Defaults to `true`.\n\n`GOTHIC_RATE_LIMIT` - `duration (e.g. 0m60s)`\n\nThe rate limit per 100 requests within the defined window to be enforced by IP address. Defaults to `5m0s`.\n\n#### JWT\n\n`GOTHIC_JWT_SECRET` - `string` **required**\n\nThe shared secret for JWT tokens. Webhooks can optionally override this with a custom value for callbacks.\n\n`GOTHIC_JWT_ALGORITHM` - `string`\n\nThe algorithm to use when signing JWT tokens `\"alg\"`. Defaults to `HS256`.\n\n`GOTHIC_JWT_ISSUER` - `string`\n\nThe issuer to include with JWT tokens `\"iss\"`. Defaults to `GOTHIC_SERVICE`, which defaults to `gothic`.\n\n`GOTHIC_JWT_AUDIENCE` - `comma seperated string array`\n\nThe audience to optionally include with JWT tokens `\"aud\"`. Value is comma separated list of resources that should\naccept the token.\n\n`GOTHIC_JWT_EXPIRATION` - `duration (e.g. 60m0s)`\n\nThe expiration time for JWT tokens `\"exp\"`. Defaults to 1 hour `60m0s`.\n\n#### ReCaptcha\n\n`GOTHIC_RECAPTCHA_KEY` - `string`\n\nYour ReCaptcha secret key. If set, gothic will expect recaptcha token with signup a/o login requests and perform a\nReCaptcha check with the supplied token and client IP. You can obtain a Recaptcha site key from Google\n[here](https://www.google.com/recaptcha/).\n\n*NOTE: The RemoteIP from REST or gRPC requests will be automatically be used as client IP*\n\n##### Testing \u0026 Development\n\n`DEBUG` builds of gothic can perform mock ReCaptcha checks. To mock a ReCaptcha check set `GOTHIC_RECAPTCHA_KEY` to\n`RECAPTCHA-DEBUG-KEY` and use `\"RECAPTCHA-DEBUG-TOKEN\"` as the ReCaptcha token when making signup or login requests.\n\n```properties\nGOTHIC_RECAPTCHA_KEY=\"RECAPTCHA-DEBUG-KEY\"\n```\n\nWhen `\"RECAPTCHA-DEBUG-KEY\"` is used, `\"RECAPTCHA-DEBUG-TOKEN\"` will always succeed. Using any other value as the\nReCaptcha token will cause the check to fail.\n\n#### Validation\n\n`GOTHIC_VALIDATION_USERNAME_REGEX` - `string`\n\nThe regex to use when validating usernames. If set, usernames will be checked on signup or update to make sure they\npass. Setting this to `\"\"` will disable the username validation. Defaults to `^[a-zA-Z0-9_]{2,255}$`\n(lower and uppercase alpha-numeric characters + underscore `_`; minimum length: 2; maximum length: 255).\n\n`GOTHIC_VALIDATION_PASSWORD_REGEX` - `string`\n\nThe regex to use when validating passwords. If set, passwords will be checked on signup or update to make sure they\npass. Setting this to `\"\"` will disable the password validation. Defaults to `^[a-zA-Z0-9[:punct:]]{8,40}$`\n(lower and uppercase alpha-numeric characters + underscore `_`; minimum length: 2; maximum length: 255).\n\nThis setting only applies to users that signup using the internal Gothic provider (email). It has no effect on signups\nor authentication with external providers.\n\n#### Cookies\n\n`GOTHIC_COOKIES_DURATION` -  `duration (e.g. 60m0s)` **REST ONLY**\n\nIf set, the cookie expiration time to use. Setting this to `0` will disable cookies. Defaults to `24h0m0s` (24 hours).\n\n### Authorization\n\n```properties\n# internal\nGOTHIC_PROVIDER_INTERNAL=true\nGOTHIC_PROVIDER_REDIRECT_URL=http://example.com/redirect\n# external providers\nGOTHIC_PROVIDER_GOOGLE_CLIENT_KEY=\"SECRET-GOOGLE-OAUTH-KEY\"\nGOTHIC_PROVIDER_GOOGLE_SECRET=\"i-am-a-secret\"\nGOTHIC_PROVIDER_GOOGLE_CALLBACK_URL=http://example.com/callback\nGOTHIC_PROVIDER_GOOGLE_SCOPES=login,confirmed\n...\nGOTHIC_PROVIDER_GITHUB_CLIENT_KEY=\"SECRET-GITHUB-OAUTH-KEY\"\nGOTHIC_PROVIDER_GITHUB_SECRET=\"i-am-a-secret\"\nGOTHIC_PROVIDER_GITHUB_CALLBACK_URL=http://example.com/callback\nGOTHIC_PROVIDER_GITHUB_SCOPES=username,email\n```\n\n`GOTHIC_PROVIDER_INTERNAL` - `boolean (\"true\" or \"false\")`\n\nIf `true` Gothic will allow users to signup and login directly using their email address. If `false` only external\nproviders (if configured) will be supported for signup and or login. Defaults to `true`.\n\n`GOTHIC_PROVIDER_REDIRECT_URL` - `string` **NOT IMPLEMENTED**\n\nThis was carried over from GoTrue. Need to implement this or drop it if no longer needed.\n\n#### External Providers\n\nGothic supports a variety of OAuth external providers for signup and login. `SAML` is not supported.\n\n[Click here](https://github.com/jrapoport/gothic/blob/master/models/types/provider/external.go) for a complete list of\nthe external providers Gothic supports.\n\n`[NAME]` is the name of the\n[external provider](https://github.com/jrapoport/gothic/blob/master/models/types/provider/external.go) you wish to\nenable and should be replaced. e.g. to enable `github` support,\n`GOTHIC_PROVIDER_[NAME]_CLIENT_KEY` would be `GOTHIC_PROVIDER_GITHUB_CLIENT_KEY`.\n\n```properties\nGOTHIC_PROVIDER_NAME_CLIENT_KEY=\"SECRET-GOOGLE-OAUTH-KEY\"\nGOTHIC_PROVIDER_NAME_SECRET=\"i-am-a-secret\"\nGOTHIC_PROVIDER_NAME_CALLBACK_URL=http://example.com/callback\nGOTHIC_PROVIDER_NAME_SCOPES=login,confirmed\n```\n\n`GOTHIC_PROVIDER_[NAME]_CLIENT_KEY` - `string` **required to enable provider**\n\nThe client key to use when authenticating with an external provider. The OAuth2 client key or cliemt ID is provided by\nthe external provider when you register with them.\n\n`GOTHIC_PROVIDER_[NAME]_SECRET` - `string`\n\nThe secret to use when authenticating with an external provider. The OAuth2 secret is provided by the external provider\nwhen you register with them.\n\n`GOTHIC_PROVIDER_[NAME]_CALLBACK_URL` - `string`\n\nThe callback URL to use when authenticating with an external provider. Typically, this URL is pre-registered with the\noauth provider and must match. The OAuth2 provider will redirect to this URL with the `code` and `state`\nvalues required to complete the OAuth2 authentication. Defaults to `\"http://:host/account/auth/callback\"`. The `:host`\ntoken defaults to, and will be automatically replaced by, the value of `GOTHIC_REST`.\n\n`GOTHIC_PROVIDER_[NAME]_SCOPES` - `comma seperated string array` *optional*\n\nA string array of additional scopes to include. By default, Gothic will include the scope(s) necessary for the user's\nemail for a given provider.\n\n#### Provider Specific\n\nAdditionally, some providers will require additional specific settings to work.\n\n##### Auth0\n\n`GOTHIC_AUTH0_DOMAIN` - `string` **required for Auth0**\n\nThe Auth0 domain to use.\n\n##### Azure AD\n\n`GOTHIC_AZURE_AD_TENANT` - `string` **required for Azure AD**\n\nThe Azure Active Directory tenant to use.\n\n##### Cloud Foundry\n\n`GOTHIC_CLOUDFOUNDRY_URL` - `string` **required FOR Cloud Foundry**\n\nThe Cloud Foundry url to use.\n\n##### Next Cloud\n\n`GOTHIC_NEXTCLOUD_URL` - `string` **required FOR Next Cloud**\n\nThe Next Cloud url to use.\n\n##### Okta\n\n`GOTHIC_OKTA_URL` - `string` **required FOR Okta**\n\nThe Okta url to use.\n\n##### Open ID Connect\n\n`GOTHIC_OPENID_CONNECT_URL` - `string` **required FOR Open ID Connect**\n\nThe Open ID Connect discovery url to use.\n\n##### Twitter\n\n`GOTHIC_TWITTER_AUTHORIZE` - `boolean (\"true\" or \"false\")` **optional FOR Twitter**\n\nIf `true` Gothic will use Twitter **authorization** instead of authentication. Defaults to `false`.\n\n### Database\n\n```properties\nGOTHIC_DB_DRIVER=mysql\nGOTHIC_DB_DSN=root@tcp(localhost:3306)/my_gothic_db\nGOTHIC_DB_AUTOMIGRATE=true\nGOTHIC_DB_NAMESPACE=prod\nGOTHIC_DB_MAX_RETRIES=3\n```\n\n`GOTHIC_DB_DRIVER` - `string` **required**\n\nThe dialect of the database you to use. Currently, `mysql`, `postgres`, `sqlserver`, and `sqlite` (or `sqlite3`) are all\nsupported. Other values will be treated as a generic sql connection and passed to the `mysql` driver.  \nDefaults to `mysql`.\n\nIn the future, direct support for other databases via `gorm.io` drivers may be added.\n\nChooses what dialect of database you want. Must be `mysql`.\n\n`GOTHIC_DB_DSN` - `string` **required**\n\nConnection string for the database.\n\n`GOTHIC_DB_AUTOMIGRATE` - `boolean (\"true\" or \"false\")`\n\nIf true, Gothic will automatically apply any necessary database migration on start-up. Defaults to `true`.\n\n`GOTHIC_DB_NAMESPACE` - `string`\n\nThe namespace prefix to use to database tables.\n\n`GOTHIC_DB_MAX_RETRIES` - `int`\n\nThe number of times to retry a database connection before failing. Each subsequent retry attempt is made using\nexponential backoff. Defaults to `3`.\n\n### Mail\n\n#### SMTP\n\n```properties\nGOTHIC_MAIL_HOST=smtp.example.com\nGOTHIC_MAIL_PORT=25\nGOTHIC_MAIL_USERNAME=user@example.com\nGOTHIC_MAIL_PASSWORD=\"smtp-password\"\nGOTHIC_MAIL_AUTHENTICATION=plain\nGOTHIC_MAIL_ENCRYPTION=none\nGOTHIC_MAIL_KEEPALIVE=true\nGOTHIC_MAIL_SPAM_PROTECTION=true\nGOTHIC_MAIL_EXPIRATION=60m0s\nGOTHIC_MAIL_SEND_LIMIT=1m0s\n```\n\n`GOTHIC_MAIL_HOST` - `string`\n\nThe hostname of the SMTP mail server. If not set, outbound emails will be disabled. Outbound mail is disabled by\ndefault. Defaults to `\"\"`.\n\n`GOTHIC_MAIL_PORT` - `int`\n\nThe port of the SMTP smtp server. Defaults to `25`\n\n`GOTHIC_MAIL_USERNAME` - `string`\n\nThe username to use if the SMTP mail server requires authentication.\n\n`GOTHIC_MAIL_PASSWORD` - `string`\n\nThe password to use if the SMTP mail server requires authentication.\n\n`GOTHIC_MAIL_AUTHENTICATION` - `string (\"plain\", \"login\", or \"cram-md5\")`\n\nThe authentication scheme to use when connecting to the SMTP mail server. Gothic supports `plain`, `login`,\nand `cram-md5` authentication schemes. Defaults to `plain`.\n\n`GOTHIC_MAIL_ENCRYPTION` - `string (\"plain\", \"login\", or \"cram-md5\")`\n\nThe encryption method to use when connecting to the SMTP mail server. Gothic supports `none`, `ssl`, and `tls`\nencryption methods. Defaults to `none`.\n\n`GOTHIC_MAIL_KEEPALIVE` - `boolean (\"true\" or \"false\")`\n\nIf `true` the mail client will send the SMTP server a keepalive `NOOP` on a regular interval. If `false`, the mail\nclient will (re)connect to the smtp mail server on send. Defaults to `true`.\n\n`GOTHIC_MAIL_SPAM_PROTECTION` - `boolean (\"true\" or \"false\")`\n\nIf `true` the mail client will attempt to verify an email address with the smtp server. If `false`, offline validaiton (\nregex) will be used. Defaults to `true`.\n\n`GOTHIC_MAIL_EXPIRATION` - `duration (e.g. 60m0s)`\n\nThe expiration to use for emailed confirmation tokens contained. Defaults to `60m0s` (1 hour).\n\n`GOTHIC_MAIL_SEND_LIMIT` - `duration (e.g. 60m0s)`\n\nThe rate limit to enforce for user email requests. If a user requests another email be sent before the deadline\n(e.g. password reset), a rate limit error will be returned. This limit has no effect opn admin users. Defaults\nto `1m0s` (1 minute).\n\n##### Format\n\n```properties\nGOTHIC_MAIL_NAME=\"Example Company\"\nGOTHIC_MAIL_LINK=http://signup.example.com\nGOTHIC_MAIL_FROM=\"Example Support \u003cdont-reply@example.com\u003e\"\nGOTHIC_MAIL_LOGO=http://mail.example.com/logo.png\n```\n\n`GOTHIC_MAIL_NAME` - `string`\n\nThe name to use in the outbound mail (e.g. \"Welcome to Gothic!\"). Defaults to `GOTHIC_SERVICE_NAME`.\n\n`GOTHIC_MAIL_LINK` - `string`\n\nThe link to use when constructing outbound email links. Defaults to `GOTHIC_SITE_URL`.\n\n`GOTHIC_MAIL_FROM` - `string`\n\nThe email address to use for outbound emails. Defaults to `:name \u003cdo-not-reply@:link_hostname\u003e`. `:name` is replaced\nby `GOTHIC_MAIL_NAME`. `:link_hostname` is replaced with the hostname of the `GOTHIC_MAIL_LINK` url.\n\n`GOTHIC_MAIL_LOGO` - `string`\n\nA URL or local file path for the logo to use in header portion of the email template. If a local file path is used, the\nimage will be embedded.\n\n#### Templates\n\n![](mail/template/testdata/template-logo-example.png)\n\n```properties\nGOTHIC_MAIL_THEME=default\nGOTHIC_MAIL_LAYOUT=./templates/mail.tmpl\nGOTHIC_MAIL_CHANGE_EMAIL_LINK_FORMAT=users/:action/:token/confirm\nGOTHIC_MAIL_CHANGE_EMAIL_SUBJECT=\"Confirm your email change\"\nGOTHIC_MAIL_CHANGE_EMAIL_TEMPLATE=./templates/change-email.tmpl\nGOTHIC_MAIL_CHANGE_EMAIL_REFERRAL_URL=http://portal.example.com\n...\nGOTHIC_MAIL_CONFIRM_USER_LINK_FORMAT=account/:action/:token/confirm\nGOTHIC_MAIL_CONFIRM_USER_SUBJECT=\"Please confirm your email address\"\nGOTHIC_MAIL_CONFIRM_USER_TEMPLATE=./templates/confirm-user.tmpl\nGOTHIC_MAIL_CONFIRM_USER_REFERRAL_URL=http://portal.example.com\n```\n\n`GOTHIC_MAIL_THEME` - `string`\n\nThe mail template theme to use. Supports `default` and `flat`. Defaults to `default`.\n\n`GOTHIC_MAIL_LAYOUT` - `string`\n\nA file path to an alternate mail layout template. Setting this value overrides Gothic's default mail layout template.\nFor an example, please see [template_layout.yaml](mail/template/testdata/template_layout.yaml).\n\n`[ACTION]` is the name of the specific email action you want to configure and should be replaced. e.g. to configure user\nconfirmation mails, `GOTHIC_MAIL_[ACTION]_SUBJECT` would be `GOTHIC_MAIL_CONFIRM_USER_SUBJECT`.\n\nGothic supports a variety of email template [ACTION]s out of the box:\n\n* `CHANGE_EMAIL`\n* `CONFIRM_USER`\n* `INVITE_USER`\n* `RESET_PASSWORD`\n* `SIGNUPCODE`\n\n```properties\nGOTHIC_MAIL_ACTION_LINK_FORMAT=/:action/:token/link\nGOTHIC_MAIL_ACTION_SUBJECT=\"Email Subject\"\nGOTHIC_MAIL_ACTION_TEMPLATE=./templates/mail.tmpl\nGOTHIC_MAIL_ACTION_REFERRAL_URL=http://portal.example.com\n```\n\n`GOTHIC_MAIL_[ACTION]_LINK_FORMAT` - `string`\n\nThe link format is the url format for the email link. If the format includes `:token` and\n`:action` strings, they will automatically be replaced with their respective values. Defaults to `/:action/#/:token`\n\n`GOTHIC_MAIL_[ACTION]_SUBJECT` - `string`\n\nThe email subject to use. Setting this value overrides Gothic's default email subjects.\n\n`GOTHIC_MAIL_[ACTION]_TEMPLATE` - `string`\n\nThe mail template to use. Setting this value overrides Gothic's default mail body template. For an example, please\nsee [template_body.yaml](mail/template/testdata/template_body.yaml)\n\n`GOTHIC_MAIL_[ACTION]_REFERRAL_URL` - `string`\n\nThe referral url to use when constructing links. Setting this value overrides `GOTHIC_MAIL_LINK`.\n\n##### Signup Codes\n\n![](mail/template/testdata/template-signup-example.png)\n\n`GOTHIC_MAIL_SIGNUPCODE_LINK_FORMAT` - `string`\n\nThe signup code template uses a slightly different template default link format: `/:action`\n\n### Signup\n\n```properties\nGOTHIC_SIGNUP_DISABLED=false\nGOTHIC_SIGNUP_AUTOCONFIRM=false\nGOTHIC_SIGNUP_CODE=false\nGOTHIC_SIGNUP_INVITES=\"admin\"\nGOTHIC_SIGNUP_USERNAME=true\nGOTHIC_SIGNUP_DEFAULT_USERNAME=true\nGOTHIC_SIGNUP_DEFAULT_COLOR=true\n```\n\n`GOTHIC_SIGNUP_DISABLED` - `boolean (\"true\" or \"false\")`\n\nIf `true` **all** user signups (internal or external) are disabled. Defaults to `false`.\n\n`GOTHIC_SIGNUP_AUTOCONFIRM` - `boolean (\"true\" or \"false\")`\n\nIf `true` new users accounts will be automatically confirmed on signup. If `false`, users will receive a confirmation\nemail. This setting only applies to Gothic's internal (email) provider, and has no effect on users that signup with an\nexternal provider (and are assumed to be confirmed). Defaults to `false`.\n\n`GOTHIC_SIGNUP_CODE` - `boolean (\"true\" or \"false\")`\n\nIf `true` a valid signup code will be required for new users accounts to signup. Defaults to `false`.\n\n`GOTHIC_SIGNUP_INVITES` - `string`\n\nThis controls the which user permissions are required to send an user invite. Possible values are:\n`user`, `admin`, or `super`. Setting this to `\"\"` disables invites completely. Defaults to `admin`.\n\n`GOTHIC_SIGNUP_USERNAME` - `boolean (\"true\" or \"false\")`\n\nIf `true` a username is also required. If a username is sent, but not required, it will still be validated. If a\nusername is required, and `GOTHIC_SIGNUP_DEFAULT_USERNAME` is `true` the default username will satisfy this condition.\nDefaults to `false`.\n\n`GOTHIC_SIGNUP_DEFAULT_USERNAME` - `boolean (\"true\" or \"false\")`\n\nIf `true` a default username will be generated if username is not present on signup. Defaults to `false`.\n\n`GOTHIC_SIGNUP_DEFAULT_COLOR` - `boolean (\"true\" or \"false\")`\n\nIf `true` a hex `color` will be generated for the user, if not present in the user data on signup. Defaults to `false`.\n\n### Webhooks\n\n```properties\nGOTHIC_WEBHOOK_URL=http://example.com/webhook/callback\nGOTHIC_WEBHOOK_EVENTS=login,confirmed\nGOTHIC_WEBHOOK_MAX_RETRIES=3\nGOTHIC_WEBHOOK_TIMEOUT=30s\n# webhook jwt\nGOTHIC_WEBHOOK_SECRET=\"webhook-jwt-secret\"\nGOTHIC_WEBHOOK_ALGORITHM=HS256\nGOTHIC_WEBHOOK_ISSUER=gothic-webhook\nGOTHIC_WEBHOOK_AUDIENCE=gothic-server-01\nGOTHIC_WEBHOOK_EXPIRATION=1m0s\n```\n\n`GOTHIC_WEBHOOK_URL` - `string`\n\nThe webhook callback URL to use. Setting this URL will enable webhook calls for events. If the url contains a `:event`\ntoken, it will automatically be replaced by the name of the event, e.g. `http://example.com/:event` =\u003e\n`http://example.com/login`. Defaults to `\"\"` (disabled).\n\n`GOTHIC_WEBHOOK_EVENTS` - `comma seperated string array`\n\nA comma separated string of the events to send via the webhook callback. Possible values are: `signup`,\n`confirmed`, `login`, `logout`, or `all`. Defaults to `\"\"` (none).\n\n`GOTHIC_WEBHOOK_MAX_RETRIES` - `int`\n\nThe number of times to retry a webhook callback before failing. Each subsequent retry attempt is made using exponential\nbackoff. Defaults to `3`.\n\n`GOTHIC_WEBHOOK_TIMEOUT` - `duration (e.g. 30s)`\n\nThe timeout to use for the webhook callback request. Defaults to `30s`.\n\n#### Webhooks JWT\n\nWebhook JWT settings should be prefixed with `GOTHIC_WEBHOOK_`.\n\nPlease see the section on [JWT](#JWT) for a more detailed explanation of these settings.\n\n### Logger\n\n#### Log\n\n```properties\nGOTHIC_LOG_PACKAGE=zap\nGOTHIC_LOG_LEVEL=info\nGOTHIC_LOG_FILE=\"./logs/gothic.log\"\n# GOTHIC_LOG_COLORS=false\n# GOTHIC_LOG_TIMESTAMP=\"Mon, 02 Jan 2006 15:04:05 -0700\"\n# GOTHIC_LOG_FIELDS=source=gothic,priority=1\n```\n\n`GOTHIC_LOG_PACKAGE` - `string`\n\nThe logger to use. Possible values are: `std`, `logrus`, or `zap`. Defaults to `std`.\n\n`GOTHIC_LOG_LEVEL` - `string`\n\nThe log level to use. Possible values are: `debug`, `info`, `warn`, `error`, `fatal`, `panic`, or `trace`. Defaults\nto `info`.\n\n`GOTHIC_LOG_FILE` - `string`\n\nThe path use for a written log file. Defaults to `\"\"` (none).\n\n\u003cs\u003e`GOTHIC_LOG_COLORS` - `boolean (\"true\" or \"false\")`\n\nIf `true` logs will be color coded. Defaults to `false`.\n\n`GOTHIC_LOG_TIMESTAMP` - `timestamp format string`\n\nThe timestamp format to use for log entries. Defaults to `2006-01-02T15:04:05.999999999Z07:00` (RFC3339Nano).\n\n`GOTHIC_LOG_FIELDS` - `comma seperated string array of key value pairs`\n\nA comma separated string of the fields to include for log entries. Format should be a comma separated list of key/value\npared. Defaults to `\"\"` (none).\u003c/s\u003e\n\n#### Tracer\n\n```properties\nGOTHIC_LOG_TRACER_ENABLED=false\nGOTHIC_LOG_TRACER_ADDRESS=tracer.example.com:9000\nGOTHIC_LOG_TRACER_TAGS=tag1=foo,tag2=bar\n```\n\n`GOTHIC_LOG_TRACER_ENABLED` - `boolean (\"true\" or \"false\")`\n\nIf `true` the global tracer will be enabled. Defaults to `false`.\n\n`GOTHIC_LOG_TRACER_ADDRESS` - `string`\n\nThe remote address to use with the global tracer. Defaults to `\"\"` (none).\n\n`GOTHIC_LOG_TRACER_TAGS` - `comma seperated string array of key value pairs`\n\nA comma separated string of the fields to include for tracer entries. Format should be a comma separated list of\nkey/value pared. Defaults to `\"\"` (none).\n\n## REST Endpoint\n\n### Account\n\n#### Signup\n\nCreates a new user account for an `email` and `password`.\n\n```http request\nPOST /account/signup\n```\n\nRequest:\n\n```json\n{\n  \"email\": \"email@example.com\",\n  \"password\": \"secret\",\n  \"username\": \"mr_example\",\n  \"code\": \"12346\",\n  \"data\": {\n    \"first_name\": \"mr\",\n    \"last_name\": \"example\",\n    \"fav_food\": \"salad\"\n  },\n  \"recaptcha\": \"u3jxPA...eyJhbG\"\n}\n  ```\n\nOnly `email` \u0026 `password` are **required**. All other fields are optional or required by their respective configuration\nsettings.\n\nResponse:\n\n```json\n{\n  \"role\": \"user\",\n  \"email\": \"email@example.com\",\n  \"username\": \"mr_example\",\n  \"data\": {\n    \"first_name\": \"mr\",\n    \"last_name\": \"example\",\n    \"fav_food\": \"salad\"\n  },\n  \"token\": {\n    \"type\": \"bearer\",\n    \"access\": \"eyJhbG...u3jxPA\",\n    \"refresh\": \"RCaUc7KcjHPMDgCWFjQUEg\",\n    \"expires_at\": \"2006-01-02T15:04:05.999999Z\"\n  }\n}\n```\n\nIf `GOTHIC_MASK_EMAILS` is `true` (the default)\nthe email returned will be: `\"em***@e******.com\"`\n\n#### Login\n\nLogs in a user with an `email` and `password`.\n\n```http request\nPOST /account/login\n```\n\nRequest:\n\n```json\n{\n  \"email\": \"email@example.com\",\n  \"password\": \"secret\",\n  \"recaptcha\": \"u3jxPA...eyJhbG\"\n}\n  ```\n\nOnly `email` \u0026 `password` are **required**. A recaptcha token is only required if `GOTHIC_RECAPTCHA_KEY`\nis set and `GOTHIC_RECAPTCHA_LOGIN` is `true`.\n\nResponse:\n\n```json\n{\n  \"role\": \"user\",\n  \"email\": \"email@example.com\",\n  \"username\": \"mr_example\",\n  \"data\": {\n    \"first_name\": \"mr\",\n    \"last_name\": \"example\",\n    \"fav_food\": \"salad\"\n  },\n  \"token\": {\n    \"type\": \"bearer\",\n    \"access\": \"eyJhbG...u3jxPA\",\n    \"refresh\": \"RCaUc7KcjHPMDgCWFjQUEg\",\n    \"expires_at\": \"2006-01-02T15:04:05.999999Z\"\n  }\n}\n```\n\nIf `GOTHIC_MASK_EMAILS` is `true` (the default) the email returned will be: `\"em***@e******.com\"`\n\n#### Logout\n\n`Authenticated` Logs a user out and revokes all refresh tokens.\n\n```http request\nGET /account/logout\n```\n\nRequest: **N/A**\n\nResponse: `HTTP 200 OK`\n\n#### Refresh Bearer Token\n\nSwaps a valid refresh `token` and issues a new jwt bearer token with updated user claims.\n\n```http request\nPOST /account/auth\n```\n\nRequest:\n\n```json\n{\n  \"token\": \"RCaUc7KcjHPMDgCWFjQUEg\"\n}\n```\n\nResponse:\n\n```json\n{\n  \"token\": {\n    \"type\": \"bearer\",\n    \"access\": \"eyJhbG...u3jxPA\",\n    \"refresh\": \"RCaUc7KcjHPMDgCWFjQUEg\",\n    \"expires_at\": \"2006-01-02T15:04:05.999999Z\"\n  }\n}\n```\n\n#### External OAuth2 Provider\n\n##### Get Authorization URL\n\nGet an authorization URL for the `:provider`. The external provider must be enabled for this call to succeed.\n\n```http request\nGET /account/auth/:provider\n```\n\nRequest: **N/A**\n\nResponse: `HTTP 302 StatusFound`\n\nCallers will be redirected to an OAuth2 authorization url with a format like:  \n`http://oauth.example.com/auth?client_id=u3jxPA\u0026response_type=code\u0026state=RCaUc7KcjH...PMDgCWFjQUEg`\n\n##### Authorize External User\n\nAuthorizes an external user account using the provider. If an account does not exist, one will be created. Externally\nauthorized users are automatically confirmed regardless of `GOTHIC_SIGNUP_AUTOCONFIRM` and can *not* change their\nemails, or passwords, etc.\n\n```http request\nPOST /account/auth/callback\n```\n\nRequest:\n\n```json\n{\n  \"state\": \"DgCWFRCaUc...HPMjQUEg\",\n  \"callback-key-1\": \"some-value\",\n  \"callback-key-2\": \"some-value\",\n  \"callback-key-3\": \"some-value\"\n}\n```\n\nOnly `state` is **required**. Any other fields returned by the external provider after calling the authorization url\nshould also be included.\n\nResponse:\n\n```json\n{\n  \"role\": \"user\",\n  \"email\": \"email@example.com\",\n  \"username\": \"mr_example\",\n  \"data\": {\n    \"first_name\": \"mr\",\n    \"last_name\": \"example\",\n    \"fav_food\": \"salad\"\n  },\n  \"token\": {\n    \"type\": \"bearer\",\n    \"access\": \"eyJhbG...u3jxPA\",\n    \"refresh\": \"RCaUc7KcjHPMDgCWFjQUEg\",\n    \"expires_at\": \"2006-01-02T15:04:05.999999Z\"\n  }\n}\n```\n\nIf `GOTHIC_MASK_EMAILS` is `true` (the default) the email returned will be: `\"em***@e******.com\"`\n\nCallers will be redirected to an OAuth2 authorization url with a format like:  \n`http://oauth.example.com/auth?client_id=u3jxPA\u0026response_type=code\u0026state=RCaUc7KcjH...PMDgCWFjQUEg`\n\n#### Send Confirm User\n\nSends an account confirmation mail to an `email` address.\n\n```http request\nPOST /account/confirm/send\n```\n\nRequest:\n\n```json\n{\n  \"email\": \"email@example.com\"\n}\n  ```\n\nResponse: `HTTP 200 OK`\n\nIf the address does not match a valid account, or the email address is invalid, an error code will be returned.\n\nIf the user exceeds the mail send rate limit `HTTP 425 StatusTooEarly` is returned.\n\n#### Confirm User\n\nConfirms a user's email address \u0026 account.\n\n```http request\nPOST /account/confirm\n```\n\nRequest:\n\n```json\n{\n  \"token\": \"RCaUc7KcjHPMDgCWFjQUEg\"\n}\n  ```\n\nResponse:\n\n```json\n{\n  \"token\": {\n    \"type\": \"bearer\",\n    \"access\": \"eyJhbG...u3jxPA\",\n    \"refresh\": \"RCaUc7KcjHPMDgCWFjQUEg\",\n    \"expires_at\": \"2006-01-02T15:04:05.999999Z\"\n  }\n}\n```\n\n#### Send Reset Password\n\nSends a password reset mail to an `email` address.\n\n```http request\nPOST /account/password/reset\n```\n\nRequest:\n\n```json\n{\n  \"email\": \"email@example.com\"\n}\n```\n\nResponse: `HTTP 200 OK`\n\nIf the address does not match a valid account, or the email address is invalid, an error code will be returned.\n\nIf the user exceeds the mail send rate limit `HTTP 425 StatusTooEarly` is returned.\n\n#### Confirm Password Reset\n\nReset's a user's account password and confirms their account (if necessary).\n\n```http request\nPOST /account/password\n```\n\nRequest:\n\n```json\n{\n  \"token\": \"RCaUc7KcjHPMDgCWFjQUEg\"\n}\n  ```\n\nResponse:\n\n```json\n{\n  \"token\": {\n    \"type\": \"bearer\",\n    \"access\": \"eyJhbG...u3jxPA\",\n    \"refresh\": \"RCaUc7KcjHPMDgCWFjQUEg\",\n    \"expires_at\": \"2006-01-02T15:04:05.999999Z\"\n  }\n}\n```\n\n### User\n\n#### Get\n\n`Authenticated` Returns the current user.\n\n```http request\nGET /user\n```\n\nRequest: **N/A**\n\nResponse:\n\n```json\n{\n  \"role\": \"user\",\n  \"email\": \"email@example.com\",\n  \"username\": \"mr_example\",\n  \"data\": {\n    \"first_name\": \"mr\",\n    \"last_name\": \"example\",\n    \"fav_food\": \"salad\"\n  }\n}\n```\n\nIf `GOTHIC_MASK_EMAILS` is `true` (the default) the email returned will be: `\"em***@e******.com\"`\n\n#### Update\n\n`Authenticated` Updates the current user\n\n```http request\nPUT /user\n```\n\nRequest:\n\n```json\n{\n  \"username\": \"sir_example\",\n  \"data\": {\n    \"first_name\": \"sir\",\n    \"last_name\": \"example\",\n    \"fav_food\": \"chips\"\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"role\": \"user\",\n  \"email\": \"email@example.com\",\n  \"username\": \"sir_example\",\n  \"data\": {\n    \"first_name\": \"sir\",\n    \"last_name\": \"example\",\n    \"fav_food\": \"chips\"\n  }\n}\n```\n\nIf `GOTHIC_MASK_EMAILS` is `true` (the default) the email returned will be: `\"em***@e******.com\"`\n\n#### Change Password\n\n`Authenticated` Changes a user's password.\n\n```http request\nPUT /user/password\n```\n\nRequest:\n\n```json\n{\n  \"password\": \"my-password\",\n  \"new_password\": \"new-password\"\n}\n```\n\nResponse:\n\n```json\n{\n  \"token\": {\n    \"type\": \"bearer\",\n    \"access\": \"eyJhbG...u3jxPA\",\n    \"refresh\": \"RCaUc7KcjHPMDgCWFjQUEg\",\n    \"expires_at\": \"2006-01-02T15:04:05.999999Z\"\n  }\n}\n```\n\n#### Request Email Change\n\n`Authenticated` Initates an email change for a user and sends a confirmation to the new address.\n\n```http request\nPUT /user/email/change\n```\n\nRequest:\n\n```json\n{\n  \"email\": \"new-email@example.com\",\n  \"password\": \"my-password\"\n}\n```\n\nResponse: `HTTP 200 OK`\n\nIf the address does not match a valid account, or the email address is invalid, an error code will be returned.\n\nIf the user exceeds the mail send rate limit `HTTP 425 StatusTooEarly` is returned.\n\n#### Confirm Email Change\n\nConfirming an email change will change the email associated with a user's account. Once changed, a user can only use the\nnew email to login.\n\n```http request\nPUT /user/email/change\n```\n\nRequest:\n\n```json\n{\n  \"token\": \"gEUQjFWCgDMPHjcK7cUaCR\"\n}\n```\n\nResponse:\n\n```json\n{\n  \"token\": {\n    \"type\": \"bearer\",\n    \"access\": \"eyJhbG...u3jxPA\",\n    \"refresh\": \"RCaUc7KcjHPMDgCWFjQUEg\",\n    \"expires_at\": \"2006-01-02T15:04:05.999999Z\"\n  }\n}\n```\n\n### Admin\n\nAdmin endpoints require a valid JWT bearer token with an **admin** user claim.\n\n#### Settings\n\n`Authenticated` Returns a summary of current configuration settings.\n\n```http request\nGET /admin/settings\n```\n\nRequest: **N/A**\n\nResponse:\n\n```json\n{\n  \"name\": \"gothic\",\n  \"version\": \"v0.0.1 (C2119)\",\n  \"status\": \"bela lugosi's dead\",\n  \"signup\": {\n    \"autoconfirm\": true,\n    \"provider\": {\n      \"internal\": \"gothic\",\n      \"external\": {\n        \"github\": true,\n        \"gitlab\": true,\n        \"google\": true\n      }\n    }\n  },\n  \"mail\": {\n    \"host\": \"127.0.0.1\",\n    \"port\": 25,\n    \"authentication\": \"plain\",\n    \"encryption\": \"none\"\n  }\n}\n  ```\n\nif signups are disabled, the `signup` fragment will return:\n\n```json\n\"signup\": {\n\"disabled\": true\n}\n```\n\nif mail is disabled, the `mail` fragment will return:\n\n```json\n\"mail\": {\n\"disabled\": true\n}\n```\n\n## GRPC\n\n## GRPC-Web\n\n## Health Check\n\nThe address health check host (currently HTTP) defaults to `[GOTHIC_HOST]:7721` and can be\nconfigured [here](#Networking).\n\n### Health\n\nReturns the health status for this gothic instance.\n\n```http request\nGET /health\n```\n\nRequest: **N/A**\n\nResponse:\n\n```json\n{\n  \"name\": \"gothic\",\n  \"version\": \"v0.0.1 (C2119)\",\n  \"status\": \"bela lugosi's dead\",\n  \"hosts\": {\n    \"rest\": {\n      \"name\": \"rest\",\n      \"address\": \"127.0.0.1:8080\",\n      \"online\": true\n    },\n    \"rpc\": {\n      \"name\": \"rpc\",\n      \"address\": \"127.0.0.1:7721\",\n      \"online\": true\n    },\n    \"rpc-web\": {\n      \"name\": \"rpc-web\",\n      \"address\": \"127.0.0.1:7729\",\n      \"onåline\": true\n    }\n  }\n}\n```\n\n## Project History\n\nThis project is a complete rewrite of [Netlify's GoTrue](https://github.com/netlify/gotrue) and is ~85-90% complete. It\nstarted off as a fork, but doesn't share a single line of code anymore.\n\nThe basic idea was to support most of the existing functionality of GoTrue while modernizing it and expanding support\nfor additional external providers and functionality. At a certain point it just made more sense to start over from\nscratch with the goal of feature parity (more or less).\n\nGroTrue relied on its own custom implementations for oauth, mail templates, smtp, jwt, etc. These have all been replaced\nwith more mature external libraries.\n\nThe original purpose was to adopt newer, more developer friendly technologies like\n[Gorm](https://gorm.io/), [gRPC](https://grpc.io/), and [gRPC Web](https://github.com/grpc/grpc-web); newer versions of\ncritical libraries for things like [JWT](https://github.com/lestrrat-go/jwx)\nand [OAuth2](https://github.com/markbates/goth); and migrate away from older libraries that are deprecated\nwith [security flaws](https://github.com/gobuffalo/uuid).\n\nThese changes allow for advances like self-contained database migration, expanded database driver support (e.g.,\nPostgreSQL), and gRPC support. Broadly speaking, they are intended to make it easier to modify and use the microservice\noutside of Netlify tool chain, and in a more active development environment.\n\nSince this project shares no code with GoTrue and is only conceptually similar at this point, I truncated the\ncommit history for clarity.\n\nWhile the Netlify team did a good job with GoTrue, their use in production means they cannot easily adopt these kinds of\nsignificant changes. In many cases, they will likely never make them given the impacts to their tooling, deployment, and\nproduction systems — which makes perfect sense for their situation.\n\nI'd like to thank Netlify team for their hard work on the original version of this microservice.\n\n\n## TODO\n* Merge rest user metadata update into update user\n* Create a grpc admin call to update a user incl. metadata\n* Add admin get user calls which return the user metadata in the response\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrapoport%2Fgothic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjrapoport%2Fgothic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrapoport%2Fgothic/lists"}