{"id":13489927,"url":"https://github.com/netlify/gotrue","last_synced_at":"2025-05-12T15:38:25.597Z","repository":{"id":37580275,"uuid":"58974323","full_name":"netlify/gotrue","owner":"netlify","description":"An SWT based API for managing users and issuing SWT tokens.","archived":false,"fork":false,"pushed_at":"2025-03-13T00:50:41.000Z","size":7327,"stargazers_count":4056,"open_issues_count":28,"forks_count":298,"subscribers_count":60,"default_branch":"master","last_synced_at":"2025-05-08T02:48:14.463Z","etag":null,"topics":["authentication","jamstack","jwt","production"],"latest_commit_sha":null,"homepage":"https://www.gotrueapi.org","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/netlify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2016-05-16T23:14:24.000Z","updated_at":"2025-05-07T22:00:18.000Z","dependencies_parsed_at":"2024-06-18T14:26:31.732Z","dependency_job_id":"4c6d3b35-3e6d-480e-9785-199f89803007","html_url":"https://github.com/netlify/gotrue","commit_stats":{"total_commits":487,"total_committers":40,"mean_commits":12.175,"dds":0.7227926078028748,"last_synced_commit":"919c35ee31af28780e92b57c91ec1fe97f6b8e1f"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netlify%2Fgotrue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netlify%2Fgotrue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netlify%2Fgotrue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netlify%2Fgotrue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netlify","download_url":"https://codeload.github.com/netlify/gotrue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253766808,"owners_count":21960996,"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":["authentication","jamstack","jwt","production"],"created_at":"2024-07-31T19:00:38.017Z","updated_at":"2025-05-12T15:38:25.550Z","avatar_url":"https://github.com/netlify.png","language":"Go","readme":"![GoTrue](gotrue.png)\n\n\u003cp align=\"center\"\u003eUser management for APIs\u003c/p\u003e\n\nGoTrue is a small open-source API written in Golang, that can act as a self-standing\nAPI service for handling user registration and authentication for Jamstack projects.\n\nIt's based on OAuth2 and JWT and will handle user signup, authentication and custom\nuser data.\n\n## Configuration\n\nYou may configure GoTrue using either a configuration file named `.env`,\nenvironment variables, or a combination of both. Environment variables are prefixed with `GOTRUE_`, and will always have precedence over values provided via file.\n\n### Top-Level\n\n```properties\nGOTRUE_SITE_URL=https://example.netlify.com/\n```\n\n`SITE_URL` - `string` **required**\n\nThe base URL your site is located at. Currently used in combination with other settings to construct URLs used in emails.\n\n`OPERATOR_TOKEN` - `string` _Multi-instance mode only_\n\nThe shared secret with an operator (usually Netlify) for this microservice. Used to verify requests have been proxied through the operator and\nthe payload values can be trusted.\n\n`DISABLE_SIGNUP` - `bool`\n\nWhen signup is disabled the only way to create new users is through invites. Defaults to `false`, all signups enabled.\n\n`GOTRUE_RATE_LIMIT_HEADER` - `string`\n\nHeader on which to rate limit the `/token` endpoint.\n\n### API\n\n```properties\nGOTRUE_API_HOST=localhost\nPORT=9999\n```\n\n`GOTRUE_API_HOST` - `string`\n\nHostname to listen on.\n\n`PORT` (no prefix) / `API_PORT` - `number`\n\nPort number to listen on. Defaults to `8081`.\n\n`GOTRUE_API_ENDPOINT` - `string` _Multi-instance mode only_\n\nControls what endpoint Netlify can access this API on.\n\n`REQUEST_ID_HEADER` - `string`\n\nIf you wish to inherit a request ID from the incoming request, specify the name in this value.\n\n`GOTRUE_API_EXPORT_SECRET` - `string`\n\nA secret that, if set, will allow exporting users for a migration to a different service.\n\n### Database\n\n```properties\nGOTRUE_DB_DRIVER=mysql\nDATABASE_URL=root@localhost/gotrue\n```\n\n`DB_DRIVER` - `string` **required**\n\nChooses what dialect of database you want. Must be `mysql`.\n\n`DATABASE_URL` (no prefix) / `DB_DATABASE_URL` - `string` **required**\n\nConnection string for the database.\n\n`DB_NAMESPACE` - `string`\n\nAdds a prefix to all table names.\n\n**Migrations Note**\n\nMigrations are not applied automatically, so you will need to run them after\nyou've built gotrue.\n\n* If built locally: `./gotrue migrate`\n* Using Docker: `docker run --rm gotrue gotrue migrate`\n\n### Logging\n\n```properties\nLOG_LEVEL=debug # available without GOTRUE prefix (exception)\nGOTRUE_LOG_FILE=/var/log/go/gotrue.log\n```\n\n`LOG_LEVEL` - `string`\n\nControls what log levels are output. Choose from `panic`, `fatal`, `error`, `warn`, `info`, or `debug`. Defaults to `info`.\n\n`LOG_FILE` - `string`\n\nIf you wish logs to be written to a file, set `log_file` to a valid file path.\n\n### Opentracing\nCurrently, only the Datadog tracer is supported.\n\n```properties\nGOTRUE_TRACING_ENABLED=true\nGOTRUE_TRACING_HOST=127.0.0.1\nGOTRUE_TRACING_PORT=8126\nGOTRUE_TRACING_TAGS=\"tag1:value1,tag2:value2\"\nGOTRUE_SERVICE_NAME=\"gotrue\"\n```\n\n`TRACING_ENABLED` - `bool`\n\nWhether tracing is enabled or not. Defaults to `false`.\n\n`TRACING_HOST` - `bool`\n\nThe tracing destination.\n\n`TRACING_PORT` - `bool`\n\nThe port for the tracing host.\n\n`TRACING_TAGS` - `string`\n\nA comma separated list of key:value pairs. These key value pairs will be added as tags to all opentracing spans.\n\n`SERVICE_NAME` - `string`\n\nThe name to use for the service.\n\n### JSON Web Tokens (JWT)\n\n```properties\nGOTRUE_JWT_SECRET=supersecretvalue\nGOTRUE_JWT_EXP=3600\nGOTRUE_JWT_AUD=netlify\n```\n\n`JWT_SECRET` - `string` **required**\n\nThe secret used to sign JWT tokens with.\n\n`JWT_EXP` - `number`\n\nHow long tokens are valid for, in seconds. Defaults to 3600 (1 hour).\n\n`JWT_AUD` - `string`\n\nThe default JWT audience. Use audiences to group users.\n\n`JWT_ADMIN_GROUP_NAME` - `string`\n\nThe name of the admin group (if enabled). Defaults to `admin`.\n\n`JWT_DEFAULT_GROUP_NAME` - `string`\n\nThe default group to assign all new users to.\n\n### External Authentication Providers\n\nWe support `bitbucket`, `github`, `gitlab`, and `google` for external authentication.\nUse the names as the keys underneath `external` to configure each separately.\n\n```properties\nGOTRUE_EXTERNAL_GITHUB_CLIENT_ID=myappclientid\nGOTRUE_EXTERNAL_GITHUB_SECRET=clientsecretvaluessssh\n```\n\nNo external providers are required, but you must provide the required values if you choose to enable any.\n\n`EXTERNAL_X_ENABLED` - `bool`\n\nWhether this external provider is enabled or not\n\n`EXTERNAL_X_CLIENT_ID` - `string` **required**\n\nThe OAuth2 Client ID registered with the external provider.\n\n`EXTERNAL_X_SECRET` - `string` **required**\n\nThe OAuth2 Client Secret provided by the external provider when you registered.\n\n`EXTERNAL_X_REDIRECT_URI` - `string` **required for gitlab**\n\nThe URI a OAuth2 provider will redirect to with the `code` and `state` values.\n\n`EXTERNAL_X_URL` - `string`\n\nThe base URL used for constructing the URLs to request authorization and access tokens. Used by `gitlab` only. Defaults to `https://gitlab.com`.\n\n### E-Mail\n\nSending email is not required, but highly recommended for password recovery.\nIf enabled, you must provide the required values below.\n\n```properties\nGOTRUE_SMTP_HOST=smtp.mandrillapp.com\nGOTRUE_SMTP_PORT=587\nGOTRUE_SMTP_USER=smtp-delivery@example.com\nGOTRUE_SMTP_PASS=correcthorsebatterystaple\nGOTRUE_SMTP_ADMIN_EMAIL=support@example.com\nGOTRUE_MAILER_SUBJECTS_CONFIRMATION=\"Please confirm\"\n```\n\n`SMTP_ADMIN_EMAIL` - `string` **required**\n\nThe `From` email address for all emails sent.\n\n`SMTP_HOST` - `string` **required**\n\nThe mail server hostname to send emails through.\n\n`SMTP_PORT` - `number` **required**\n\nThe port number to connect to the mail server on.\n\n`SMTP_USER` - `string`\n\nIf the mail server requires authentication, the username to use.\n\n`SMTP_PASS` - `string`\n\nIf the mail server requires authentication, the password to use.\n\n`SMTP_MAX_FREQUENCY` - `number`\n\nControls the minimum amount of time that must pass before sending another signup confirmation or password reset email. The value is the number of seconds. Defaults to 900 (15 minutes).\n\n`MAILER_AUTOCONFIRM` - `bool`\n\nIf you do not require email confirmation, you may set this to `true`. Defaults to `false`.\n\n`MAILER_URLPATHS_INVITE` - `string`\n\nURL path to use in the user invite email. Defaults to `/`.\n\n`MAILER_URLPATHS_CONFIRMATION` - `string`\n\nURL path to use in the signup confirmation email. Defaults to `/`.\n\n`MAILER_URLPATHS_RECOVERY` - `string`\n\nURL path to use in the password reset email. Defaults to `/`.\n\n`MAILER_URLPATHS_EMAIL_CHANGE` - `string`\n\nURL path to use in the email change confirmation email. Defaults to `/`.\n\n`MAILER_SUBJECTS_INVITE` - `string`\n\nEmail subject to use for user invite. Defaults to `You have been invited`.\n\n`MAILER_SUBJECTS_CONFIRMATION` - `string`\n\nEmail subject to use for signup confirmation. Defaults to `Confirm Your Signup`.\n\n`MAILER_SUBJECTS_RECOVERY` - `string`\n\nEmail subject to use for password reset. Defaults to `Reset Your Password`.\n\n`MAILER_SUBJECTS_EMAIL_CHANGE` - `string`\n\nEmail subject to use for email change confirmation. Defaults to `Confirm Email Change`.\n\n`MAILER_TEMPLATES_INVITE` - `string`\n\nURL path to an email template to use when inviting a user.\n`SiteURL`, `Email`, and `ConfirmationURL` variables are available.\n\nDefault Content (if template is unavailable):\n\n```html\n\u003ch2\u003eYou have been invited\u003c/h2\u003e\n\n\u003cp\u003eYou have been invited to create a user on {{ .SiteURL }}. Follow this link to accept the invite:\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"{{ .ConfirmationURL }}\"\u003eAccept the invite\u003c/a\u003e\u003c/p\u003e\n```\n\n`MAILER_TEMPLATES_CONFIRMATION` - `string`\n\nURL path to an email template to use when confirming a signup.\n`SiteURL`, `Email`, and `ConfirmationURL` variables are available.\n\nDefault Content (if template is unavailable):\n\n```html\n\u003ch2\u003eConfirm your signup\u003c/h2\u003e\n\n\u003cp\u003eFollow this link to confirm your user:\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"{{ .ConfirmationURL }}\"\u003eConfirm your mail\u003c/a\u003e\u003c/p\u003e\n```\n\n`MAILER_TEMPLATES_RECOVERY` - `string`\n\nURL path to an email template to use when resetting a password.\n`SiteURL`, `Email`, and `ConfirmationURL` variables are available.\n\nDefault Content (if template is unavailable):\n\n```html\n\u003ch2\u003eReset Password\u003c/h2\u003e\n\n\u003cp\u003eFollow this link to reset the password for your user:\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"{{ .ConfirmationURL }}\"\u003eReset Password\u003c/a\u003e\u003c/p\u003e\n```\n\n`MAILER_TEMPLATES_EMAIL_CHANGE` - `string`\n\nURL path to an email template to use when confirming the change of an email address.\n`SiteURL`, `Email`, `NewEmail`, and `ConfirmationURL` variables are available.\n\nDefault Content (if template is unavailable):\n\n```html\n\u003ch2\u003eConfirm Change of Email\u003c/h2\u003e\n\n\u003cp\u003eFollow this link to confirm the update of your email from {{ .Email }} to {{ .NewEmail }}:\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"{{ .ConfirmationURL }}\"\u003eChange Email\u003c/a\u003e\u003c/p\u003e\n```\n\n`WEBHOOK_URL` - `string`\n\nUrl of the webhook receiver endpoint. This will be called when events like `validate`, `signup` or `login` occur.\n\n`WEBHOOK_SECRET` - `string`\n\nShared secret to authorize webhook requests. This secret signs the [JSON Web Signature](https://tools.ietf.org/html/draft-ietf-jose-json-web-signature-41) of the request. You *should* use this to verify the integrity of the request. Otherwise others can feed your webhook receiver with fake data.\n\n`WEBHOOK_RETRIES` - `number`\n\nHow often GoTrue should try a failed hook.\n\n`WEBHOOK_TIMEOUT_SEC` - `number`\n\nTime between retries (in seconds).\n\n`WEBHOOK_EVENTS` - `list`\n\nWhich events should trigger a webhook. You can provide a comma separated list.\nFor example to listen to all events, provide the values `validate,signup,login`.\n\n## Endpoints\n\nGoTrue exposes the following endpoints:\n\n* **GET /settings**\n\n  Returns the publicly available settings for this gotrue instance.\n\n  ```json\n  {\n    \"external\": {\n      \"bitbucket\": true,\n      \"github\": true,\n      \"gitlab\": true,\n      \"google\": true\n    },\n    \"disable_signup\": false,\n    \"autoconfirm\": false\n  }\n  ```\n\n* **POST /signup**\n\n  Register a new user with an email and password.\n\n  ```json\n  {\n    \"email\": \"email@example.com\",\n    \"password\": \"secret\"\n  }\n  ```\n\n  Returns:\n\n  ```json\n  {\n    \"id\": \"11111111-2222-3333-4444-5555555555555\",\n    \"email\": \"email@example.com\",\n    \"confirmation_sent_at\": \"2016-05-15T20:49:40.882805774-07:00\",\n    \"created_at\": \"2016-05-15T19:53:12.368652374-07:00\",\n    \"updated_at\": \"2016-05-15T19:53:12.368652374-07:00\"\n  }\n  ```\n\n* **POST /invite**\n\n  Invites a new user with an email.\n\n  ```json\n  {\n    \"email\": \"email@example.com\"\n  }\n  ```\n\n  Returns:\n\n  ```json\n  {\n    \"id\": \"11111111-2222-3333-4444-5555555555555\",\n    \"email\": \"email@example.com\",\n    \"confirmation_sent_at\": \"2016-05-15T20:49:40.882805774-07:00\",\n    \"created_at\": \"2016-05-15T19:53:12.368652374-07:00\",\n    \"updated_at\": \"2016-05-15T19:53:12.368652374-07:00\",\n    \"invited_at\": \"2016-05-15T19:53:12.368652374-07:00\"\n  }\n  ```\n\n* **POST /verify**\n\n  Verify a registration or a password recovery. Type can be `signup` or `recovery`\n  and the `token` is a token returned from either `/signup` or `/recover`.\n\n  ```json\n  {\n    \"type\": \"signup\",\n    \"token\": \"confirmation-code-delivered-in-email\",\n    \"password\": \"12345abcdef\"\n  }\n  ```\n\n  `password` is required for signup verification if no existing password exists.\n\n  Returns:\n\n  ```json\n  {\n    \"access_token\": \"jwt-token-representing-the-user\",\n    \"token_type\": \"bearer\",\n    \"expires_in\": 3600,\n    \"refresh_token\": \"a-refresh-token\"\n  }\n  ```\n\n* **POST /recover**\n\n  Password recovery. Will deliver a password recovery mail to the user based on\n  email address.\n\n  ```json\n  {\n    \"email\": \"email@example.com\"\n  }\n  ```\n\n  Returns:\n\n  ```json\n  {}\n  ```\n\n* **POST /token**\n\n  This is an OAuth2 endpoint that currently implements\n  the password, refresh_token, and authorization_code grant types\n\n  ```\n  grant_type=password\u0026username=email@example.com\u0026password=secret\n  ```\n\n  or\n\n  ```\n  grant_type=refresh_token\u0026refresh_token=my-refresh-token\n  ```\n\n  Once you have an access token, you can access the methods requiring authentication\n  by settings the `Authorization: Bearer YOUR_ACCESS_TOKEN_HERE` header.\n\n  Returns:\n\n  ```json\n  {\n    \"access_token\": \"jwt-token-representing-the-user\",\n    \"token_type\": \"bearer\",\n    \"expires_in\": 3600,\n    \"refresh_token\": \"a-refresh-token\"\n  }\n  ```\n\n* **GET /user**\n\n  Get the JSON object for the logged in user (requires authentication)\n\n  Returns:\n\n  ```json\n  {\n    \"id\": \"11111111-2222-3333-4444-5555555555555\",\n    \"email\": \"email@example.com\",\n    \"confirmation_sent_at\": \"2016-05-15T20:49:40.882805774-07:00\",\n    \"created_at\": \"2016-05-15T19:53:12.368652374-07:00\",\n    \"updated_at\": \"2016-05-15T19:53:12.368652374-07:00\"\n  }\n  ```\n\n* **PUT /user**\n\n  Update a user (Requires authentication). Apart from changing email/password, this\n  method can be used to set custom user data.\n\n  ```json\n  {\n    \"email\": \"new-email@example.com\",\n    \"password\": \"new-password\",\n    \"data\": {\n      \"key\": \"value\",\n      \"number\": 10,\n      \"admin\": false\n    }\n  }\n  ```\n\n  Returns:\n\n  ```json\n  {\n    \"id\": \"11111111-2222-3333-4444-5555555555555\",\n    \"email\": \"email@example.com\",\n    \"confirmation_sent_at\": \"2016-05-15T20:49:40.882805774-07:00\",\n    \"created_at\": \"2016-05-15T19:53:12.368652374-07:00\",\n    \"updated_at\": \"2016-05-15T19:53:12.368652374-07:00\"\n  }\n  ```\n\n* **POST /logout**\n\n  Logout a user (Requires authentication).\n\n  This will revoke all refresh tokens for the user. Remember that the JWT tokens\n  will still be valid for stateless auth until they expire.\n\n## TODO\n\n* Schema for custom user data in config file\n","funding_links":[],"categories":["Go","Authentication","others","jamstack","User Management"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetlify%2Fgotrue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetlify%2Fgotrue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetlify%2Fgotrue/lists"}