Admin Client
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.
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=truegates the public/signupendpoint 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 matchesErrAlreadyRegistered.
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.
Generate a link without sending mail
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.