Running an authentication server in production is not an easy feat. We recommend using Supabase Auth which gets regular security updates.

Otherwise, please make sure you setup a process to promptly update to the latest version. You can do that by following this repository, specifically the Releases and Security Advisories sections.

​
Backward compatibility

Auth uses the Semantic Versioning scheme. Here are some further clarifications on backward compatibility guarantees:

Go API compatibility

Auth is not meant to be used as a Go library. There are no guarantees on backward API compatibility when used this way regardless which version number changes.

Patch

Changes to the patch version guarantees backward compatibility with:

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

Guaranteed examples:

  • A column won’t change its type.
  • A table won’t change its primary key.
  • An index will not be removed.
  • A uniqueness constraint will not be removed.
  • A REST API will not be removed.
  • Parameters to REST APIs will work equivalently as before (or better, if a bug has been fixed).
  • Configuration will not change.

Not guaranteed examples:

  • A table may add new columns.
  • Columns in a table may be reordered.
  • Non-unique constraints may be removed (database level checks, null, default values).
  • JWT may add new properties.

Minor

Changes to minor version guarantees backward compatibility with:

  • REST API
  • JWT structure
  • Configuration

Exceptions to these guarantees will be made only when serious security issues are found that can’t be remedied in any other way.

Guaranteed examples:

  • Existing APIs may be deprecated but continue working for the next few minor version releases.
  • Configuration changes may become deprecated but continue working for the next few minor version releases.
  • Already issued JWTs will be accepted, but new JWTs may be with a different structure (but usually similar).

Not guaranteed examples:

  • Removal of JWT fields after a deprecation notice.
  • Removal of certain APIs after a deprecation notice.
  • Removal of sign-in with external providers, after a deprecation notice.
  • Deletion, truncation, significant schema changes to tables, indexes, views, functions.

We aim to provide a deprecation notice in execution logs for at least two major version releases or two weeks if multiple releases go out. Compatibility will be guaranteed while the notice is live.

Major

Changes to the major version do not guarantee any backward compatibility with previous versions.

​
Inherited features

Certain inherited features from the Netlify codebase are not supported by Supabase and they may be removed without prior notice in the future. This is a comprehensive list of those features:

  1. Multi-tenancy via the instances table i.e. GOTRUE_MULTI_INSTANCE_MODE configuration parameter.
  2. System user (zero UUID user).
  3. Super admin via the is_super_admin column.
  4. Group information in JWTs via GOTRUE_JWT_ADMIN_GROUP_NAME and other configuration fields.
  5. Symmetrics JWTs. In the future it is very likely that Auth will begin issuing asymmetric JWTs (subject to configuration), so do not rely on the assumption that only HS256 signed JWTs will be issued long term.

Note that this is not an exhaustive list and it may change.

​
Best practices when self-hosting

These are some best practices to follow when self-hosting to ensure backward compatibility with Auth:

  1. Do not modify the schema managed by Auth. You can see all of the migrations in the migrations directory.
  2. Do not rely on schema and structure of data in the database. Always use Auth APIs and JWTs to infer information about users.
  3. Always run Auth behind a TLS-capable proxy such as a load balancer, CDN, nginx or other similar software.