GoTrue

Admin Client

Call GoTrue's privileged admin endpoints from server code — invite users, generate action links, ban and delete accounts.

auth/gotrueadmin calls the GoTrue endpoints that require a service-role token: inviting users, generating action links, and reading, updating, or deleting users. It is a client, not a proxy. It registers no routes, has no HTTP handlers, and there is nothing to mount.

Everything here is privileged. The client signs its own admin token, which can read and change any account, so it must only ever be constructed in server code and pointed at GoTrue's internal URL. Do not wire these calls into a public route, and do not add them to the proxy allowlist: the proxy's endpoints are the ones safe to expose to a browser, and this is the opposite of that. Put your own authorization in front of anything that reaches it.

Construct it

import "github.com/sulv-io/ezz/auth/gotrueadmin"

admin, err := gotrueadmin.New(gotrueadmin.Config{
    BaseURL:   os.Getenv("GOTRUE_INTERNAL_URL"), // http://gotrue:9999
    JWTSecret: os.Getenv("GOTRUE_JWT_SECRET"),
})

BaseURL and JWTSecret are required and validated, so a typo fails at construction rather than on the first invite. HTTP overrides the client, TokenTTL the token lifetime (60 seconds by default), and Role the role claim (service_role by default, which matches GoTrue's GOTRUE_JWT_ADMIN_ROLES).

The secret is passed in rather than read from the environment, so the client is configured the same way as everything else in your service.

The token

Each call mints a fresh short-lived HS256 token with a top-level role claim, plus iat and exp. It is sent as a bearer token, never logged, and never included in an error message.

auth.HMACProvider cannot mint this token. Its custom claims are nested under custom, while GoTrue matches a top-levelrole claim against GOTRUE_JWT_ADMIN_ROLES. That is why this package signs its own, rather than reusing the provider.

Invite a user

user, err := admin.Invite(ctx, "ada@example.com", gotrueadmin.InviteOptions{
    Data:       map[string]any{"role": "merchant"},
    RedirectTo: "https://app.example.com/accept",
})
if errors.Is(err, gotrueadmin.ErrAlreadyRegistered) {
    // the address already has a confirmed account
}

GoTrue creates the user if absent and emails the invitation. Three behaviours are worth knowing:

  • Invites work with signups disabled. GOTRUE_DISABLE_SIGNUP=true gates the public /signup endpoint only. Invite is a separate gate, which is what makes invite-only launches possible.
  • Re-inviting a pending address succeeds. It sends a fresh token and creates no duplicate user.
  • An existing confirmed account is an error, 422 email_exists, which matches ErrAlreadyRegistered.

RedirectTo travels in the query string on this endpoint, because GoTrue's invite parameters carry only email and data. It must be on GoTrue's allowed redirect list, or GoTrue falls back to its configured site URL.

When your own renderer sends the email, ask for the link instead:

link, err := admin.GenerateLink(ctx, gotrueadmin.LinkRequest{
    Type:       gotrueadmin.LinkTypeInvite,
    Email:      "ada@example.com",
    RedirectTo: "https://app.example.com/accept",
})
// link.ActionLink, link.EmailOTP, link.HashedToken, link.VerificationType, link.User

Types are invite, magiclink, recovery, signup, email_change_current, and email_change_new. Here RedirectTo goes in the body, not the query string — the two endpoints genuinely differ, and the client sends each where GoTrue reads it.

ActionLink signs in whoever opens it. Treat it as a credential: send it to the address it belongs to, and keep it out of logs and error reports.

VerificationType is not always the type you asked for. A magiclink for an address GoTrue does not know becomes a signup, so read it back rather than assuming.

Read, update, delete

user, err := admin.GetUser(ctx, id)
page, err := admin.ListUsers(ctx, 1, 50) // page.Users, page.Aud, page.Total

ban := "24h"                              // "none" lifts a ban
_, err = admin.UpdateUser(ctx, id, gotrueadmin.UserUpdate{
    BanDuration: &ban,
    AppMetadata: map[string]any{"suspended": true},
})

err = admin.DeleteUser(ctx, id, true)     // soft delete

Only the fields you set on UserUpdate are sent, so an unset map is left alone rather than cleared. Pointer fields exist for the cases where false and "not set" differ.

Put authorization data in AppMetadata, never UserMetadata: users can change their own user_metadata through the proxy.

Passing 0 for page or perPage leaves the parameter off and lets GoTrue apply its own default. Total comes from GoTrue's X-Total-Count header, and counts every user in the audience rather than the ones on this page.

DeleteUser with soft true anonymises the row and keeps it, so references to it survive. A hard delete removes it, which is what an account-deletion request usually means.

Errors

Every failed call returns an *APIError carrying the HTTP Status, GoTrue's Code, and its Msg:

var apiErr *gotrueadmin.APIError
if errors.As(err, &apiErr) && apiErr.Status == 422 {
    log.Printf("gotrue refused: %s", apiErr.Code)
}

Two sentinels are matched with errors.Is: ErrAlreadyRegistered and ErrNotFound. Both key off GoTrue's error_code, not its message text, so a wording change upstream does not break them.

Next steps

  • Proxy for the public, browser-facing half.
  • Deployment for the GoTrue configuration these calls assume.
Copyright © 2026