authclient

package module
v0.10.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 1, 2026 License: MIT Imports: 15 Imported by: 0

README

ab0t Auth Service — Go SDK

Go Reference

A Go client for the ab0t Auth Service — authentication, authorization, organizations, API keys, SSO, and Zanzibar-style relationship-based access control.

  • Standard library only. No require block, no transitive dependencies. This module gets embedded in other people's binaries, so it brings nothing with it. CI enforces this.
  • Interface-first. Validator and Authorizer are two-method interfaces, so your handlers are testable against fakes with no live auth service.
  • Fails closed. Errors surface as errors. Nothing in this SDK turns a failure into an "allow".
go get github.com/ab0t-com/auth-sdk-go

Requires Go 1.23+.

Command line

go install github.com/ab0t-com/auth-sdk-go/cmd/ab0t-auth@latest

ab0t-auth login --key ab0t_sk_…      # or --email you@example.com
ab0t-auth whoami
ab0t-auth can user:alice view doc:123 --store my-store
ab0t-auth doctor                     # why isn't it working?
ab0t-auth help can                   # deep help: purpose, example, failures, what's next
ab0t-auth about                      # licence, source, support, the Go SDK

Rehearse writes with --dry-run, time-box a grant with --expires 24h, clear an object with revoke-all, and get the whole capability catalogue as data with help --json.

Same zero dependencies as the library. NO_COLOR is honoured, --json works on every command, colour is never the only signal, and exit codes carry the answer (0 allowed, 2 denied) so if ab0t-auth can …; then works in a script. ab0t-auth help lists everything.

Quick start

import auth "github.com/ab0t-com/auth-sdk-go"

// "" selects the production service (auth.DefaultBaseURL).
client := auth.New("",
    auth.WithAPIKey(os.Getenv("AUTH_SERVICE_KEY")), // this service's own ab0t_sk_ key
    auth.WithExpectedAudience("my-service"),        // reject tokens minted for someone else
)

// AuthN: who is this?
actor, err := client.ValidateToken(ctx, token)
if err != nil || !actor.Valid {
    return errUnauthorized
}
fmt.Println(actor.UserID, actor.OrgID, actor.Permissions)

// AuthZ: may they do this?
ok, err := client.Authorize(ctx, token, "economy.transfer", auth.Resource{Type: "wallet", ID: "w1"})
if err != nil {
    return errUnavailable // 503 — do NOT treat this as allow
}
if !ok {
    return errForbidden
}

A complete, runnable HTTP middleware example lives in examples/gate:

go run ./examples/gate

The two primitives

Depend on these interfaces, not on *Client. That is what makes your code testable.

type Validator interface {
    ValidateToken(ctx context.Context, token string) (*Actor, error)
}

type Authorizer interface {
    Authorize(ctx context.Context, token, action string, resource Resource) (bool, error)
}

*Client satisfies both. In tests, substitute a struct with the answers you want.

A credential may be a user JWT or an agent/service API key (ab0t_sk_…). Authorize routes each to the endpoint that can resolve it, so agents and humans go through exactly the same call. IsAPIKey(cred) tells them apart if you need to.

Three rules for using this safely

  1. A nil error is not a yes. Check the boolean too — Authorize returns (false, nil) for a legitimate denial.
  2. Never turn an error into an allow. A transport failure or a 5xx means you do not know. Answer 503, not 200. An auth-service blip must not silently unlock your write surface.
  3. Set an expected audience. Without WithExpectedAudience, a token minted for a different service will validate against yours.

What is covered

Area Methods
AuthN ValidateToken, ValidateAPIKey, Introspect, JWKS, OrgJWKS, login/refresh/logout
AuthZ (RBAC) Authorize, CheckPermission, CheckPermissionPublic, grant/revoke, permission registry
AuthZ (ReBAC / Zanzibar) ZanzibarCheck(+Bulk/Wildcard), Expand, List(Objects|Users), relationship write/delete, namespaces, hierarchy, visualize, watch
Users CRUD, profile, password reset, self-delete (DeleteCurrentUser)
Organizations & teams CRUD, membership, roles, invitations, session revocation
API keys & delegation create/list/update/delete, service accounts, delegation grant/check
SSO / federation providers, SAML, OAuth/OIDC, attribute mappings, JIT provisioning
Mesh ListMeshProviders, GetMeshProvider, PublishMeshProvider
Admin & system password policy, privilege elevation, super-admin grants, quotas, events, health

Full operation → method map: COVERAGE.md.

Two authorization models — pick deliberately

The service exposes two authorization systems and they are easy to cross-wire:

Account / RBAC Zanzibar / ReBAC
Endpoint /permissions/check, /auth/validate-token /zanzibar/stores/{store_id}/…
Identity user_id combined typed string, e.g. user:alice
Question "does this user hold this permission?" "does this subject have this relation to this object?"
Use for coarse capabilities — admin.write, users.read per-object sharing — "who can view this document"

For most route gating you want Authorize. Reach for Zanzibar when the answer depends on a relationship to a specific object.

Zanzibar without the ceremony

The raw methods mirror the HTTP API exactly — every operation reachable, every type matching the wire. That is the right foundation, but it is not what using it should feel like. Bind the store once and ask questions:

store := client.Store(storeID, callerToken)

// Can alice view this document?
ok, err := store.Can(ctx, "user", "alice", "view", "doc", "123")

// Make her the owner.
err = store.Relate(ctx, "user", "alice", "owner", "doc", "123")

// Which documents can she view?  (the query behind a filtered index page)
docs, err := store.WhatCan(ctx, auth.Subject("user", "alice"), "view", "doc")

// Who can view this one?  (the query behind a sharing dialog — groups expanded)
users, err := store.WhoCan(ctx, auth.Object("doc", "123"), "view")

// Several questions, one round trip.
ok, err = store.CanAll(ctx,
    auth.Check("user", "alice", "view", "doc", "1"),
    auth.Check("user", "alice", "view", "doc", "2"),
)

// Why did it decide that?  (reason + the relationship path it followed)
res, err := store.Why(ctx, auth.Subject("user", "alice"), "view", auth.Object("doc", "123"))

Types are separate arguments on purpose. ("user", "alice") is impossible to get wrong; "user:alice" is easy to get wrong, and getting it wrong produces a silent deny rather than an error. Use the *ID variants (CanID, RelateID, UnrelateID) when you already hold a combined id.

Every boolean here fails closed: an error is false, an empty batch is false (nothing asked is not everything permitted), and a bulk response with the wrong number of results is an error rather than a guess. Relate treats success:false as an error even on a 200, because a write that is reported as refused is not a write.

This layer is over the raw methods, never instead of them — ZanzibarCheck, WriteRelationships and the rest keep working unchanged, so anything the service can do stays reachable.

Transport and resilience

  • Timeout: 15s default — WithTimeout.
  • Retries: 2 by default with exponential backoff, honouring Retry-After on 429/503 — WithMaxRetries, WithBackoff.
  • JWKS: cached 10 minutes, bounded at 512 key sets with stalest-first eviction, and serves a stale-but-good set if a refresh fails rather than failing your requests.

⚠️ Retries apply to non-idempotent POSTs too. A create call whose write committed before the response was lost will be retried, and on an endpoint with no natural dedup key that can produce a duplicate side effect — two invitations, two orgs, two emitted webhooks. Where once-only semantics matter, use WithMaxRetries(0) for that client or call.

HTTP middleware

authmw gates routes, so you do not copy-paste a gate out of an example:

import "github.com/ab0t-com/auth-sdk-go/authmw"

gate := &authmw.Gate{V: client, A: client}
mux.Handle("POST /admin", gate.Require("admin.write", "service", adminHandler))
http.ListenAndServe(":8080", gate.Authenticate(mux))

401 no credential · 403 denied · 503 auth service unreachable · else your handler.

That 503 is the whole point. "I could not decide" is not "yes" — a gate that allows on error turns an auth-service blip into an open door, quietly, because the requests succeed and nothing pages anyone. Fail-closed is the default and FailOpen must be set deliberately.

Testing

Test doubles ship with the SDK — you do not have to write them:

import "github.com/ab0t-com/auth-sdk-go/authclienttest"

gate := &authmw.Gate{V: authclienttest.Allow(), A: authclienttest.Allow()}       // 200
gate = &authmw.Gate{V: authclienttest.Deny(), A: authclienttest.Deny()}          // 403
gate = &authmw.Gate{V: authclienttest.Unavailable(), A: authclienttest.Unavailable()} // 503

Test the third one. Everyone tests allow and deny; almost nobody tests what their handler does when the auth service is unreachable — the one path where a mistake means an outage silently unlocks the write surface.

Fake also records what was asked, so you can assert the action actually reached the authorizer (if it stopped being sent, every authenticated caller would be authorized for everything, and every status-code assertion would still pass):

f := authclienttest.Allow()
// … drive your handler …
for _, c := range f.Calls() {
    if c.Method == "Authorize" && c.Action != "economy.transfer" { t.Error(...) }
}

To exercise the real client — its retries, decoding and error mapping — use the fake service:

srv := authclienttest.NewServer()
defer srv.Close()
client := auth.New(srv.URL())
srv.SetStatus(503)   // now assert your handler answers 503, not 200

Observability

client := auth.New("", auth.WithObserver(func(i auth.RequestInfo) {
    slog.Info("auth", "endpoint", i.Endpoint, "status", i.Status,
        "ms", i.Duration.Milliseconds(), "attempt", i.Attempt)
}))

One event per attempt, so retries are visible rather than hidden inside one slow call. The endpoint has its query string stripped, so it works as a metric label. No headers and no bodies are carried — a path and a status cannot leak a credential.

Known gaps

Four methods in authzmodel.go (ReadAuthorizationModel, ListAuthorizationModels, WriteAuthorizationModel, WriteAndDeleteRelationships) target routes the service does not expose yet. They ship as forward-looking stubs, each carrying a SERVER-GAP doc note, and TestAuthorizationModel_IsStillAServerGap records executably that they 404 today. When the routes land, that test fails — which is the signal to remove the warnings.

Versioning

Pre-1.0. Minor releases may change contracts when the service's contract changes — see CHANGELOG.md, which marks breaking changes explicitly. Pin a version.

The live OpenAPI spec is the source of truth, not this SDK. If they disagree, this SDK has a bug — please report it.

Checks

There is no automatic CI on this repository yet, by choice. Run the checks locally:

make check    # gofmt + go vet + go test + the stdlib-only assertion
make drift    # compare this SDK against the LIVE OpenAPI spec

A manual-dispatch-only workflow is staged at .ci-pending/; see the README there.

make drift

The spec is the source of truth and it moves. make drift fetches https://auth.service.ab0t.com/openapi.json and reports two things:

  • MISSING — an operation in the spec with no SDK method: a capability you cannot reach.
  • PHANTOM — an SDK request path the spec does not define: a call that would 404.

PHANTOM is the more dangerous direction. A missing method is a gap someone notices; a phantom one looks like a working method until it is called.

Current status: 283/283 operations reachable, plus the four documented known gaps, which the tool lists separately and tells you to remove the warnings from if the server ever ships them.

make drift-strict exits non-zero on any disagreement, if you want it as a gate.

Documentation and skills
docs/USAGE.md The cookbook — task-shaped recipes, install to troubleshooting
docs/CLI.md Complete command and flag reference
skills/auth-sdk-go-concepts The mental model: two authz systems, typed ids, tenancy, nested orgs
skills/auth-sdk-go-cli Operating the CLI
skills/auth-sdk-go-integration Wiring the Go library into a service

The skills/ directory is agent-readable: point your coding agent at it and it can use this SDK without you explaining the model first.

Contributing

See CONTRIBUTING.md. Security issues: SECURITY.md — report privately, never in a public issue.

License

MIT — see LICENSE.

Upgrading

Breaking upgrades ship a migration kit under migrations/vFROM-to-vTO/: run its migrate-check.sh against your repo to find every call site to change, and read its MIGRATION.md. For v0.10.0 see migrations/v0.9.2-to-v0.10.0/.

Documentation

Overview

Package authclient is an isolated, typed Go client for the ab0t Auth Service (an Okta-style enterprise auth/permission stack served at https://auth.service.ab0t.com).

Isolation

This package is its own Go module (github.com/ab0t-com/auth-sdk-go) and depends ONLY on the standard library. It has no dependency on any particular server, simulation, or any game internals. The server can adopt it later to gate routes via Authorize/ValidateToken without coupling to auth-service internals or to this package's transport details.

What the auth service provides

Multi-provider authentication (password, OAuth/OIDC, SAML, passwordless), multi-tenant organizations, RBAC + a Zanzibar-style relationship engine, JWKS-backed JWTs, federation/SSO, API keys and service accounts. Tokens are JWTs bound to an active org (tenant); access tokens are short-lived and refreshed with a long-lived refresh token. Services authenticate to each other with API keys (prefix "ab0t_sk_") sent as bearer tokens.

Surface

The client groups the endpoints a resource server / agent actually needs: 

Authentication: Login, Register, Refresh, Logout, SwitchOrganization, Me, Delegate
OAuth2/OIDC:    OAuthAuthorizeURL, OAuthCallback
Revocation:     RevokeToken, RevokeTokenPublic
Token/authz:    ValidateToken, ValidateAPIKey, Introspect, CheckPermission, Authorize
JWKS:           JWKS, RefreshJWKS, OrgJWKS, SigningKey (TTL-cached)
Users:          GetMyProfile, UpdateMyProfile, ChangeMyPassword, GetUser,
                UpdateUser, Activate/DeactivateUser, VerifyUserEmail, *PasswordReset
Orgs/tenants:   Create/Get/Update/DeleteOrganization, GetOrgHierarchy,
                ListOrgUsers, UpdateOrgUserRole, RemoveOrgUser, Invite*,
                List/RevokeOrgSessions, RevokeUserSessions
Teams/groups:   Create/Get/Update/DeleteTeam, *TeamMember*, GetTeamPermissions
Roles/RBAC:     GetRoles, Grant/RevokePermission (query-param based),
                registry (services, valid-permissions, validate, stats, register)
Zanzibar ReBAC: ZanzibarCheck(+Bulk/Wildcard), Expand, List(Objects|Users),
                Write/DeleteRelationships (single tuple), namespaces,
                grant/revoke, hierarchy/team setup, visualize, migrate, watch.
                Uses combined typed-string ids ("doc:123", "user:alice"); build
                them with Object()/Subject(). Request/response types match the
                live OpenAPI (verified 2026-07-12).
Authz model:    Write/Read/List/EnsureAuthorizationModel,
                WriteAndDeleteRelationships (atomic), List(Relationships|Objects)Paged,
                DeleteAllRelationshipsForObject
                (forward-looking: model management + transact + list-relationships
                 pagination are SERVER-GAPs not in the auth service OpenAPI;
                 the REAL schema surface is namespaces. See COVERAGE.md.)
Providers/SSO:  Create/List/Get/Update/Delete/TestProvider, federation
                SSO sessions/config/domains, attribute mappings, JIT, stats
API keys:       List/Create/Get/Update/DeleteAPIKey (CreateServiceAccount)
Delegation:     Grant/Revoke/Check/ListDelegation
Provisioning:   SCIM 2.0 users/groups + Schemas/ResourceTypes/ServiceProviderConfig,
                HRIS and SCIM connection management (see scim.go, hris.go)
Admin:          password policy, JWKS rotate/revoke/generate/activate/cleanup,
                circuit breakers, elevate privileges, audit, emergency revoke
Super-admin:    time-bound Grant/Revoke/Extend/Approve + active-grants/audit
Interactive:    OAuthAuthorize, PushedAuthorizationRequest, OAuthToken,
                RefreshTokenForm, dynamic client registration, email-verify,
                password-reset, OIDC/OAuth discovery, JWKS health
Hosted auth:    OrgLogin/Register/Token/Refresh/Logout, OrgAuthProviders,
                OrgSSOInitiate/Callback, login-config, hosted pages, invites
Passwordless:   WebAuthn register/authenticate + credentials, magic links,
                recovery codes, devices
SAML:           IdP/SP SSO/ACS/SLO/metadata, SP CRUD, attribute mappings,
                certificates, analytics
Email admin:    system + per-org config/templates/preview/test
Events:         webhook subscription CRUD + test/toggle/stats
Network ACL:    policies, emergency overrides, temp allowlists, violations
Forward-auth:   ForwardAuth/Live/Pass/Fail edge decisions (GET/POST/HEAD)
Quotas/reports: MyQuotaUsage, CheckQuota, QuotaTiers, Submit/List/Dismiss/ResolveReport
System:         Health, Status, Discover, Metrics, JWKSMetrics, alerts, help

The client covers the operations a resource server / agent needs across the surfaces listed above. The Zanzibar ReBAC and account/RBAC request/response contracts were reconciled against the live OpenAPI on 2026-07-12; a small number of forward-looking authorization-model / transact / paging capabilities have no server route yet and are marked SERVER-GAP in authzmodel.go. See COVERAGE.md for the operation -> method map and the known gaps.

Two interfaces decouple callers from the concrete client: 

Validator  — resolve a bearer token to an Actor (who + tenant + permissions).
Authorizer — decide whether a token may perform an action on a resource.

The route-gating primitive is: 

allowed, _ := client.Authorize(ctx, token, "world.write", authclient.Resource{Type: "world", ID: "w1"})

Quick start 

c := authclient.New("https://auth.service.ab0t.com",
        authclient.WithAPIKey("ab0t_sk_..."))   // server's service key (optional)

tok, err := c.Login(ctx, authclient.LoginRequest{Email: e, Password: p})
actor, err := c.ValidateToken(ctx, tok.AccessToken)
ok, err := c.Authorize(ctx, tok.AccessToken, "world.write",
        authclient.Resource{Type: "world", ID: "w1"})

See README.md for the full mapping to endpoints.

Index

Constants

View Source 
const (
	ScopeOrgRead     = "org.read"
	ScopeOrgAdmin    = "org.admin"
	ScopeSystemAdmin = "system.admin"

	ScopeUsersRead    = "users.read"
	ScopeUsersWrite   = "users.write"
	ScopeUsersInvite  = "users.invite"
	ScopeUsersElevate = "users.elevate"

	ScopeTeamsRead  = "teams.read"
	ScopeTeamsWrite = "teams.write"

	ScopeSAMLRead  = "saml.read"
	ScopeSAMLAdmin = "saml.admin"
	ScopeSSOAdmin  = "sso.admin"

	ScopeZanzibarAdmin = "zanzibar.admin"

	ScopePermissionsRegister = "permissions.register"

	ScopeEventsSubscribe = "events.subscribe"
	ScopeEventsRead      = "events.read"
	ScopeEventsUpdate    = "events.update"
	ScopeEventsDelete    = "events.delete"
	ScopeEventsTest      = "events.test"

	ScopeAdminPasswordPolicyRead   = "admin.password_policy.read"
	ScopeAdminPasswordPolicyWrite  = "admin.password_policy.write"
	ScopeAdminPasswordResetWrite   = "admin.password_reset.write"
	ScopeAdminReportsRead          = "admin.reports.read"
	ScopeAdminAuditRead            = "admin.audit.read"
	ScopeAdminServiceAccountsWrite = "admin.service_accounts.write"
	ScopeAdminUsersElevate         = "admin.users.elevate"
	ScopeAdminTestWrite            = "admin.test.write"

	ScopeAdminJWKSRead   = "admin.jwks.read"
	ScopeAdminJWKSWrite  = "admin.jwks.write"
	ScopeAdminJWKSRotate = "admin.jwks.rotate"
	ScopeAdminJWKSRevoke = "admin.jwks.revoke"
	ScopeAdminJWKSAdmin  = "admin.jwks.admin"

	ScopeAdminCircuitBreakerRead  = "admin.circuit_breaker.read"
	ScopeAdminCircuitBreakerWrite = "admin.circuit_breaker.write"

	ScopeAdminMetricsRead = "admin.metrics.read"
)

This file defines the permission/role vocabulary (dot-permissions) the auth service enforces via RBAC + Zanzibar. They are provided as typed constants so SDK callers (especially admin/service clients) can reference required scopes without stringly-typed literals. The vocabulary mirrors section "Permission/ role vocabulary" of the FULL contract.

View Source 
const APIKeyPrefix = "ab0t_sk_"

APIKeyPrefix is the prefix of service-to-service API keys.

View Source 
const DefaultBaseURL = "https://auth.service.ab0t.com"

DefaultBaseURL is the production auth service.

View Source 
const DefaultValidationCacheMaxEntries = 4096

DefaultValidationCacheMaxEntries bounds the number of distinct cached decisions. Entries are keyed by credential (hashed) plus request shape, so an unbounded map grows by one entry per distinct credential ever seen and never shrinks — a leak keyed by tenant. The bound is generous; eviction costs only a revalidation.

View Source 
const DefaultValidationCacheNegativeTTL = 5 * time.Second

DefaultValidationCacheNegativeTTL is the TTL applied to a NEGATIVE decision (the service answered, and said no) when the caller does not choose one. It is deliberately much shorter than the positive TTL: a denial that has just been fixed by granting a permission should start working promptly, and caching denials aggressively buys little — a denied caller is not usually a hot path.

View Source 
const DefaultValidationCacheTTL = 30 * time.Second

DefaultValidationCacheTTL is the recommended starting point for a hot path: short enough that a revocation is noticed in seconds, long enough that a service under load makes one validation call per credential per interval instead of one per request. It is a SUGGESTION, not a fallback — a non-positive TTL disables the cache rather than substituting this value, so "off" cannot be reached by accident and cannot be left ambiguous.

View Source 
const Version = "0.10.2"

Version is the SDK's released version. It is reported in the User-Agent of every request, so the auth service can attribute traffic and spot clients that are running a version with a known-bad contract.

Keep this in step with the git tag: a tag of v0.1.0 means Version == "0.1.0".

Variables

This section is empty.

Functions

func CredentialHeader added in v0.10.0 

func CredentialHeader(cred string) (name, value string)

CredentialHeader reports the header name and value the auth service expects for cred, so callers never have to think about it.

WHY THIS EXISTS: the service deliberately keeps the two credential systems on separate transports, and gets it wrong in opposite directions on different routes. An ab0t_sk_ key presented as "Authorization: Bearer <key>" is rejected 401 at the forward-auth edge (an asserted anti-credential-confusion invariant); a key presented as a bare "Authorization: <key>" is invisible to the API routes, because FastAPI's HTTPBearer only populates credentials for the Bearer scheme. X-API-Key is the one transport every API-key-accepting surface reads, so that is what we send for keys. JWTs keep Authorization: Bearer, unchanged.

Shape decides, not configuration: an ab0t_sk_ prefix means API key; a JWS compact shape means JWT; anything else falls back to Bearer, which is the historical behavior and keeps third-party/opaque tokens working.

func IsAPIKey 

func IsAPIKey(cred string) bool

IsAPIKey reports whether a credential is a service API key (vs. a user JWT) based on the ab0t_sk_ prefix.

func IsBadRequest 

func IsBadRequest(err error) bool

IsBadRequest reports whether err is an APIError with a 400 status.

func IsConflict 

func IsConflict(err error) bool

IsConflict reports whether err is an APIError with a 409 status.

func IsForbidden 

func IsForbidden(err error) bool

IsForbidden reports whether err is an APIError with a 403 status (authenticated but lacking the required permission/role).

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound reports whether err is an APIError with a 404 status.

func IsRateLimited 

func IsRateLimited(err error) bool

IsRateLimited reports whether err is an APIError with a 429 status.

func IsRetryable 

func IsRetryable(err error) bool

IsRetryable reports whether err represents a transient condition that the transport considers safe to retry (429 or 5xx).

func IsServerError 

func IsServerError(err error) bool

IsServerError reports whether err is an APIError with a 5xx status.

func IsUnauthorized 

func IsUnauthorized(err error) bool

IsUnauthorized reports whether err is an APIError with a 401 status (authentication failed / token missing, expired, or invalid).

func IsValidationError 

func IsValidationError(err error) bool

IsValidationError reports whether err is an APIError with a 422 status (request body failed server-side validation).

func LooksLikeJWT added in v0.10.0 

func LooksLikeJWT(cred string) bool

LooksLikeJWT reports whether a credential has the shape of a JWS compact serialization: three non-empty, dot-separated segments and no whitespace. It is a SHAPE test, not a validity test — it neither verifies the signature nor parses the claims. Use it to decide how to TRANSPORT a credential, never to decide whether to trust one.

func Object 

func Object(typ, id string) string

Object builds a combined Zanzibar object/subject id ("type:id"), e.g. Object("calendar", "123") == "calendar:123". Subject is an alias for the same shape (e.g. Subject("user", "bob") == "user:bob").

func StatusCode 

func StatusCode(err error) int

StatusCode returns the HTTP status code carried by err, or 0 if err is not an APIError.

func Subject 

func Subject(typ, id string) string

Subject builds a combined Zanzibar subject id ("type:id"), e.g. Subject("user", "bob") == "user:bob". Userset subjects append "#relation" yourself, e.g. Subject("group", "eng")+"#member".

Types

type APIError 

type APIError struct {
	// StatusCode is the HTTP status code of the response.
	StatusCode int
	// Method is the HTTP method of the originating request.
	Method string
	// Endpoint is the request path (no query string) that produced the error.
	Endpoint string
	// Code is a machine-readable error code parsed from the body, if any
	// (e.g. "invalid_grant", "token_expired"). Empty when not present.
	Code string
	// Message is a human-readable message parsed from the body, if any.
	Message string
	// RequestID echoes any X-Request-ID / request correlation id returned.
	RequestID string
	// Body is the raw (possibly truncated) response body.
	Body string
}

APIError is returned for non-2xx responses from the auth service. It captures the HTTP status, the endpoint that produced it, a best-effort machine-readable error code parsed from the response body, and the raw body for diagnostics.

Callers should generally branch on the Is* helpers (IsUnauthorized, etc.) rather than comparing StatusCode directly.

func AsAPIError 

func AsAPIError(err error) (*APIError, bool)

AsAPIError returns the underlying *APIError if err wraps one.

func (*APIError) Error 

func (e *APIError) Error() string

type APIKey 

type APIKey struct {
	ID          string   `json:"id"`
	Name        string   `json:"name,omitempty"`
	Prefix      string   `json:"prefix,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
	OrgID       string   `json:"org_id,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	ExpiresAt   string   `json:"expires_at,omitempty"`
	// IsActive/LastUsed/RateLimit are the fields the server actually sends
	// (APIKeyResponse marks them required). They replace the earlier `enabled`
	// and `last_used_at`, which the server never sent — those were always zero.
	IsActive  bool   `json:"is_active,omitempty"`
	LastUsed  string `json:"last_used,omitempty"`
	RateLimit int64  `json:"rate_limit,omitempty"`
}

APIKey is the metadata for a key (no secret). APIKeyResponse in the API.

type APIKeyCreate 

type APIKeyCreate struct {
	Name        string   `json:"name"`
	Permissions []string `json:"permissions,omitempty"`
	OrgID       string   `json:"org_id,omitempty"`
	ExpiresAt   string   `json:"expires_at,omitempty"`
	Audience    []string `json:"audience,omitempty"`
}

APIKeyCreate is the body for POST /api-keys/.

type APIKeyUpdate 

type APIKeyUpdate struct {
	Name        *string   `json:"name,omitempty"`
	Permissions *[]string `json:"permissions,omitempty"`
	// IsActive enables/disables the key. The server field is `is_active`; an
	// earlier revision sent `enabled`, which the server ignored — so toggling a
	// key through the SDK silently did nothing.
	IsActive  *bool          `json:"is_active,omitempty"`
	RateLimit *int64         `json:"rate_limit,omitempty"`
	Metadata  map[string]any `json:"metadata,omitempty"`
	// ExpiresAt is not in the server's update schema (kept for compatibility;
	// the server ignores it — update expiry is not currently supported).
	ExpiresAt *string `json:"expires_at,omitempty"`
}

APIKeyUpdate is the body for PUT /api-keys/{key_id}.

type APIKeyValidation 

type APIKeyValidation struct {
	Valid       bool     `json:"valid"`
	UserID      string   `json:"user_id,omitempty"`
	OrgID       string   `json:"org_id,omitempty"`
	Email       string   `json:"email,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
	Audience    []string `json:"audience,omitempty"`
	ExpiresAt   string   `json:"expires_at,omitempty"`
	// Reason is the failure reason for an invalid key. The wire field is "error"
	// (shared with token validation); the Go field keeps the name Reason for
	// source compatibility.
	Reason string `json:"error,omitempty"`
	// IsDelegation/ActingAs/DelegationScope/DelegationChain describe an act-as key
	// (a service account acting on another principal's behalf). Zero for a direct
	// service key. See Actor for the JWT-side twin.
	IsDelegation    bool     `json:"is_delegation,omitempty"`
	ActingAs        string   `json:"acting_as,omitempty"`
	DelegationScope []string `json:"delegation_scope,omitempty"`
	DelegationChain []string `json:"delegation_chain,omitempty"`
}

APIKeyValidation is the result of validating a service API key.

POST /auth/validate-api-key returns the SAME schema as /auth/validate-token (TokenValidationResponse), so this type mirrors Actor: it carries email/audience/expiry and the delegation fields, because a service account CAN act on another principal's behalf (an on-behalf-of / act-as key). An earlier revision modeled only valid/user_id/org_id/permissions and read the failure reason from a "reason" field the server does not send (it sends "error"), so Reason was always empty; both are fixed here.

type APIKeyWithToken 

type APIKeyWithToken struct {
	APIKey
	// Token is the secret key (prefix "ab0t_sk_"), returned exactly once at
	// creation. The wire field is `key` — the service does not send `token`, so an
	// earlier revision that tagged this `json:"token"` never populated it.
	Token string `json:"key,omitempty"`
}

APIKeyWithToken is the create response, which includes the secret exactly once. It embeds APIKey (id, name, permissions, created_at, expires_at, rate_limit) and adds the secret.

type AccessCheckResponse added in v0.10.0 

type AccessCheckResponse struct {
	Status           string   `json:"status"`
	Enforced         bool     `json:"enforced"`
	NetworkZone      string   `json:"network_zone"`
	OrgID            string   `json:"org_id,omitempty"`
	PermissionsScope []string `json:"permissions_scope,omitempty"`
}

AccessCheckResponse is the result of a network access-check. 

type ActiveMagicLink struct {
	Token     string `json:"token,omitempty"`
	Email     string `json:"email,omitempty"`
	CreatedAt string `json:"created_at,omitempty"`
	ExpiresAt string `json:"expires_at,omitempty"`
}

ActiveMagicLink describes one outstanding magic link.

type ActiveMagicLinksResponse 

type ActiveMagicLinksResponse struct {
	Links       []ActiveMagicLink `json:"links"`
	ActiveLinks json.RawMessage   `json:"active_links,omitempty"`
	Count       int64             `json:"count,omitempty"`
}

ActiveMagicLinksResponse lists a user's active magic links.

type Actor 

type Actor struct {
	Valid       bool     `json:"valid"`
	UserID      string   `json:"user_id,omitempty"`
	OrgID       string   `json:"org_id,omitempty"`
	Email       string   `json:"email,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
	Audience    []string `json:"audience,omitempty"`
	ExpiresAt   string   `json:"expires_at,omitempty"`
	Error       string   `json:"error,omitempty"`
	// IsDelegation reports whether this token is acting on another user's behalf.
	IsDelegation bool `json:"is_delegation,omitempty"`
	// ActingAs is the user_id the delegated token is acting on behalf of.
	ActingAs string `json:"acting_as,omitempty"`
	// DelegationScope is the permission set the delegation is limited to.
	DelegationScope []string `json:"delegation_scope,omitempty"`
	// DelegationChain records the principals in a chained delegation, in order.
	DelegationChain []string `json:"delegation_chain,omitempty"`
	// contains filtered or unexported fields
}

Actor is the resolved identity behind a token (TokenValidationResponse). It is the canonical "who + tenant + capabilities" the server authorizes on.

func (Actor) HasPermission 

func (a Actor) HasPermission(p string) bool

HasPermission reports whether the actor's resolved permission list contains p. Note: this only reflects permissions the service chose to return (use IncludePermissions or RequiredPermissions when validating). Prefer Client.Authorize / Client.CheckPermission for authoritative decisions.

type AlertEntry 

type AlertEntry struct {
	Level     string `json:"level,omitempty"`
	Message   string `json:"message,omitempty"`
	Timestamp string `json:"timestamp,omitempty"`
	Source    string `json:"source,omitempty"`
}

AlertEntry is one recent operational alert.

type ApprovalRequestModel 

type ApprovalRequestModel struct {
	GrantID string `json:"grant_id"`
	Approve bool   `json:"approve"`
	Comment string `json:"comment,omitempty"`
}

ApprovalRequestModel is the body for POST /super-admin/approve.

type AttributeMapping 

type AttributeMapping struct {
	ID         string `json:"id,omitempty"`
	SourceAttr string `json:"source_attribute"`
	TargetAttr string `json:"target_attribute"`
	Transform  string `json:"transform,omitempty"`
	ProviderID string `json:"provider_id,omitempty"`
}

AttributeMapping is one IdP attribute -> local attribute mapping.

type AttributeMappingCreateResponse 

type AttributeMappingCreateResponse struct {
	Mapping   AttributeMapping `json:"mapping"`
	Message   string           `json:"message,omitempty"`
	MappingID string           `json:"mapping_id,omitempty"`
}

AttributeMappingCreateResponse is the result of POST /federation/attribute-mappings.

type AttributeMappingListResponse 

type AttributeMappingListResponse struct {
	Mappings []AttributeMapping `json:"mappings"`
	Total    int                `json:"total,omitempty"`
	Count    int64              `json:"count,omitempty"`
}

AttributeMappingListResponse is the result of GET /federation/attribute-mappings.

type AuthorizationModel 

type AuthorizationModel struct {
	// SchemaVersion is the model schema language version (e.g. "1.1").
	SchemaVersion string `json:"schema_version,omitempty"`
	// DSL is the model expressed as OpenFGA/Zanzibar model text.
	DSL string `json:"dsl,omitempty"`
	// TypeDefinitions is the structured form of the model (type -> relations ->
	// rewrites). Left generic (untyped) so any server schema shape is expressible.
	TypeDefinitions []map[string]any `json:"type_definitions,omitempty"`
}

AuthorizationModel is a versioned authorization schema: the object types, their relations, and the userset rewrites (unions, computed usersets such as "viewer from parent", wildcards, subject-relation subjects) that checks evaluate against. Provide EITHER DSL (the OpenFGA/Zanzibar model text) OR TypeDefinitions (the equivalent structured form); the server parses whichever is supplied and returns the canonical form plus a version id.

SERVER-GAP: authorization-model management is not part of the auth service OpenAPI as of 2026-07-12; these types describe a forward-looking contract.

type AuthorizationModelResponse 

type AuthorizationModelResponse struct {
	AuthorizationModelID string           `json:"authorization_model_id"`
	SchemaVersion        string           `json:"schema_version,omitempty"`
	TypeDefinitions      []map[string]any `json:"type_definitions,omitempty"`
	DSL                  string           `json:"dsl,omitempty"`
	CreatedAt            string           `json:"created_at,omitempty"`
}

AuthorizationModelResponse is one stored model version (read / list item).

type AuthorizationResponse 

type AuthorizationResponse struct {
	RedirectURI string         `json:"redirect_uri,omitempty"`
	Location    string         `json:"location,omitempty"`
	Code        string         `json:"code,omitempty"`
	State       string         `json:"state,omitempty"`
	ConsentURL  string         `json:"consent_url,omitempty"`
	Extra       map[string]any `json:"extra,omitempty"`
}

AuthorizationResponse is returned by GET /auth/authorize. For an interactive browser flow the service typically issues a redirect; when accessed programmatically it returns the location and any pending consent metadata.

type AuthorizationServerMetadata 

type AuthorizationServerMetadata = OpenIDConfiguration

AuthorizationServerMetadata is the RFC 8414 OAuth metadata document.

type Authorizer 

type Authorizer interface {
	Authorize(ctx context.Context, token, action string, resource Resource) (bool, error)
}

Authorizer decides whether a token may perform an action on a resource. This is the intended route-gating primitive.

type BulkCheckRequest 

type BulkCheckRequest struct {
	Checks []CheckPermissionRequest `json:"checks"`
}

BulkCheckRequest is the body for POST /zanzibar/stores/{store_id}/check/bulk. Matches OpenAPI schema BulkCheckRequest (required: checks).

type BulkCheckResults 

type BulkCheckResults []CheckPermissionResponse

BulkCheckResults is the result of a bulk check: one CheckPermissionResponse per element of the BulkCheckRequest.Checks slice, IN THE SAME ORDER.

The wire shape is a bare JSON array (OpenAPI: `type: array, items: CheckPermissionResponse`, verified against the live spec 2026-07-25), not an object. An earlier release of this SDK decoded it into a struct with a `results` map — a documented best-effort guess made while the server had no declared response schema. The server has since declared one and the guess was wrong, which made EVERY successful bulk check return a json.UnmarshalTypeError to the caller. If you are upgrading from that release, this type and ZanzibarCheckBulk's return type both changed.

func (BulkCheckResults) AllAllowed 

func (b BulkCheckResults) AllAllowed() bool

AllAllowed reports whether every check was allowed. An empty result set returns false — "nothing was checked" is not "everything is permitted".

func (BulkCheckResults) Allowed 

func (b BulkCheckResults) Allowed(i int) bool

Allowed reports the decision for the i'th check in the request. It returns false for an out-of-range index rather than panicking: a short response from the server must fail CLOSED, never allow.

type ChangePassword 

type ChangePassword struct {
	CurrentPassword string `json:"current_password"`
	NewPassword     string `json:"new_password"`
}

ChangePassword is the body for POST /users/me/change-password.

type CheckPermissionRequest 

type CheckPermissionRequest struct {
	Subject    string         `json:"subject"`
	Permission string         `json:"permission"`
	Object     string         `json:"object"`
	OrgID      string         `json:"org_id,omitempty"`
	Context    map[string]any `json:"context,omitempty"`
	// ConsistencyToken requests a read at least as fresh as the write that
	// produced it (read-after-write). Maps to `consistency_token`.
	ConsistencyToken string `json:"consistency_token,omitempty"`
}

CheckPermissionRequest is the body for POST /zanzibar/stores/{store_id}/check (and the elements of a BulkCheckRequest). Matches OpenAPI schema CheckPermissionRequest (required: subject, permission, object).

func Check added in v0.3.0 

func Check(subjectType, subjectID, permission, objectType, objectID string) CheckPermissionRequest

Check builds one element of a CanAll/CanAny batch. 

ok, err := store.CanAll(ctx,
    authclient.Check("user", "alice", "view", "doc", "1"),
    authclient.Check("user", "alice", "view", "doc", "2"),
)

type CheckPermissionResponse 

type CheckPermissionResponse struct {
	Allowed     bool     `json:"allowed"`
	Reason      string   `json:"reason,omitempty"`
	Path        []string `json:"path,omitempty"`
	Cached      bool     `json:"cached,omitempty"`
	CheckTimeMS float64  `json:"check_time_ms,omitempty"`
}

CheckPermissionResponse is the result of a Zanzibar check. Matches OpenAPI schema CheckPermissionResponse (required: allowed).

type CircuitBreakerResetAllResponse 

type CircuitBreakerResetAllResponse struct {
	ResetCount int             `json:"reset_count,omitempty"`
	Message    string          `json:"message,omitempty"`
	NewStatus  json.RawMessage `json:"new_status,omitempty"`
	ResetBy    string          `json:"reset_by,omitempty"`
	Warning    string          `json:"warning,omitempty"`
}

CircuitBreakerResetAllResponse is the result of resetting all breakers.

type CircuitBreakerResetResponse 

type CircuitBreakerResetResponse struct {
	Name    string `json:"name,omitempty"`
	Reset   bool   `json:"reset,omitempty"`
	Message string `json:"message,omitempty"`
}

CircuitBreakerResetResponse is the result of resetting one breaker.

type CircuitBreakerStatusResponse 

type CircuitBreakerStatusResponse struct {
	Breakers        map[string]any  `json:"breakers,omitempty"`
	CircuitBreakers json.RawMessage `json:"circuit_breakers,omitempty"`
	OverallHealth   json.RawMessage `json:"overall_health,omitempty"`
	SLAImpact       json.RawMessage `json:"sla_impact,omitempty"`
}

CircuitBreakerStatusResponse is the result of GET /admin/circuit-breakers/status.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a typed, isolated client for the auth service. It is safe for concurrent use.

func New 

func New(baseURL string, opts ...Option) *Client

New constructs a Client. baseURL may be "" to use DefaultBaseURL.

func (*Client) AcceptInvitePage 

func (c *Client) AcceptInvitePage(ctx context.Context, slug, inviteToken string) (map[string]any, error)

AcceptInvitePage fetches the invite-acceptance page payload for a tenant slug. GET /organizations/{slug}/accept-invite. token is the invite token query param.

func (*Client) ActivateSigningKey 

func (c *Client) ActivateSigningKey(ctx context.Context, kid, callerToken string) (*KeyActivateResponse, error)

ActivateSigningKey activates a signing key by kid. POST /admin/jwks/activate/{kid}.

func (*Client) ActivateUser 

func (c *Client) ActivateUser(ctx context.Context, userID, callerToken string) (*MessageDetailResponse, error)

ActivateUser reactivates a user (requires users.write). POST /users/{user_id}/activate.

func (*Client) AddTeamMember 

func (c *Client) AddTeamMember(ctx context.Context, teamID string, req TeamMemberAdd, callerToken string) (*MessageResponse, error)

AddTeamMember adds a member to a team (requires teams.write). POST /teams/{team_id}/members.

func (*Client) AuthorizationServerMetadata 

func (c *Client) AuthorizationServerMetadata(ctx context.Context) (*AuthorizationServerMetadata, error)

AuthorizationServerMetadata fetches the RFC 8414 metadata document. GET /.well-known/oauth-authorization-server.

func (*Client) Authorize 

func (c *Client) Authorize(ctx context.Context, token, action string, resource Resource) (bool, error)

Authorize reports whether token may perform action on resource. This is the route-gating primitive.

resource may be the zero Resource for non-resource-scoped actions.

A credential may be a user JWT or a service/agent API key (ab0t_sk_…).

Resource scoping

When resource is NON-zero, Authorize asks a resource-scoped question and routes it to the permission decision point that contractually evaluates the resource: it resolves the subject from the credential, then calls CheckPermission (POST /permissions/check) with the resource. This is uniform across auth backends. It exists because not every backend's validate-token endpoint honors the resource fields: a backend that ignores them would answer the broader "does this subject hold the permission at all?" instead of "…on THIS resource?", which is a silent privilege escalation across resources. Routing to the resource-aware PDP removes that divergence.

Authorize FAILS CLOSED: an invalid token, or any error resolving the subject or reaching the PDP, returns false (with the error). It never falls back to an unscoped allow.

Cost: a resource-scoped Authorize performs subject-resolution and then the PDP check (two round trips). The optional validation cache (WithValidationCache) absorbs the subject-resolution call. A resource-less Authorize is a single validate-token capability check, unchanged.

func (*Client) BaseURL 

func (c *Client) BaseURL() string

BaseURL returns the configured base URL.

func (*Client) ChangeMyPassword 

func (c *Client) ChangeMyPassword(ctx context.Context, token string, req ChangePassword) (*MessageResponse, error)

ChangeMyPassword changes the caller's password. POST /users/me/change-password.

func (*Client) CheckDelegation 

func (c *Client) CheckDelegation(ctx context.Context, targetUserID, token string) (*DelegationCheckResponse, error)

CheckDelegation reports whether the caller may act on behalf of a target user. GET /delegation/check/{target_user_id}.

func (*Client) CheckPermission 

func (c *Client) CheckPermission(ctx context.Context, req PermissionCheckRequest, callerToken string) (*PermissionDecision, error)

CheckPermission performs an authoritative RBAC check for a specific user. POST /permissions/check. Requires the caller (service API key or a token with users.read) to be authorized; configure WithAPIKey or pass a privileged token via callerToken (use "" to fall back to the configured service API key).

func (*Client) CheckPermissionPublic 

func (c *Client) CheckPermissionPublic(ctx context.Context, req PermissionCheckRequest) (*PermissionDecision, error)

CheckPermissionPublic performs a permission check via the public POST /auth/check-permission endpoint (no caller auth required). This is the account/RBAC surface: it takes PermissionCheckRequest{user_id,...}, NOT a Zanzibar tuple.

func (*Client) CheckQuota 

func (c *Client) CheckQuota(ctx context.Context, resourceType, token string) (*QuotaCheckResponse, error)

CheckQuota checks the caller's quota for a resource type. GET /quotas/check/{resource_type}.

func (*Client) CircuitBreakerStatus 

func (c *Client) CircuitBreakerStatus(ctx context.Context, callerToken string) (*CircuitBreakerStatusResponse, error)

CircuitBreakerStatus returns the status of all circuit breakers. GET /admin/circuit-breakers/status.

func (*Client) CleanupSigningKeys 

func (c *Client) CleanupSigningKeys(ctx context.Context, req KeyCleanupRequest, callerToken string) (*KeyCleanupResponse, error)

CleanupSigningKeys removes old signing keys. POST /admin/jwks/cleanup.

func (*Client) ConfigureHRISConnection added in v0.10.0 

func (c *Client) ConfigureHRISConnection(ctx context.Context, orgID string, req HRISConfigureRequest, callerToken string) (*HRISConnectionStatus, error)

ConfigureHRISConnection configures (or updates) an org's HRIS connection. POST /organizations/{org_id}/hris/connection. Requires org.admin.

func (*Client) ConfirmPasswordResetAuth 

func (c *Client) ConfirmPasswordResetAuth(ctx context.Context, req PasswordResetConfirm) (*PasswordResetConfirmResponse, error)

ConfirmPasswordResetAuth confirms a password reset via the auth endpoint. POST /auth/password-reset/confirm.

func (*Client) ConfirmVerificationEmail 

func (c *Client) ConfirmVerificationEmail(ctx context.Context, token string) error

ConfirmVerificationEmail confirms an email-verification token. POST /auth/verify-email/confirm.

func (*Client) CreateAPIKey 

func (c *Client) CreateAPIKey(ctx context.Context, req APIKeyCreate, token string) (*APIKeyWithToken, error)

CreateAPIKey mints a new API key. The secret token is returned exactly once. POST /api-keys/. Requires a user JWT (BearerJWT).

func (*Client) CreateAttributeMapping 

func (c *Client) CreateAttributeMapping(ctx context.Context, req AttributeMapping, callerToken string) (*AttributeMappingCreateResponse, error)

CreateAttributeMapping creates a federation attribute mapping (requires system.admin). POST /federation/attribute-mappings.

func (*Client) CreateDomainToken 

func (c *Client) CreateDomainToken(ctx context.Context, token string) (*DomainTokenResponse, error)

CreateDomainToken mints a domain-scoped SSO token. POST /federation/sso/create-token.

func (*Client) CreateEmergencyOverride 

func (c *Client) CreateEmergencyOverride(ctx context.Context, req EmergencyOverrideRequest, callerToken string) (*EmergencyOverrideCreateResponse, error)

CreateEmergencyOverride creates an emergency network override. POST /network-policy/emergency-override. Requires org.admin.

func (*Client) CreateEventSubscription 

func (c *Client) CreateEventSubscription(ctx context.Context, req EventSubscriptionCreate, token string) (*EventSubscription, error)

CreateEventSubscription creates a webhook subscription. POST /events/subscriptions. Requires events.subscribe.

func (*Client) CreateNamespace 

func (c *Client) CreateNamespace(ctx context.Context, storeID string, req NamespaceRequest, callerToken string) (*ZanzibarMessageResponse, error)

CreateNamespace defines a namespace (requires zanzibar.admin). POST /zanzibar/stores/{store_id}/namespaces.

func (*Client) CreateNetworkPolicy 

func (c *Client) CreateNetworkPolicy(ctx context.Context, req CreateNetworkPolicyRequest, callerToken string) (*NetworkPolicyCreateResponse, error)

CreateNetworkPolicy creates an IP/network access policy. POST /network-policy/. Requires org.admin.

func (*Client) CreateOrganization 

func (c *Client) CreateOrganization(ctx context.Context, req OrganizationCreate, token string) (*Organization, error)

CreateOrganization creates a new organization/tenant. POST /organizations/.

func (*Client) CreateProvider 

func (c *Client) CreateProvider(ctx context.Context, req ProviderConfigCreate, callerToken string) (*Provider, error)

CreateProvider creates a provider/SSO connection (requires org.admin). POST /providers/.

func (*Client) CreateSSODomain 

func (c *Client) CreateSSODomain(ctx context.Context, domain string, req SSODomainConfigRequest, callerToken string) (*SSODomainConfigResponse, error)

CreateSSODomain creates an SSO domain config (requires org.admin). POST /federation/sso/domains/{domain}.

func (*Client) CreateSSOSession 

func (c *Client) CreateSSOSession(ctx context.Context, token string) (*SSOSessionCreateResponse, error)

CreateSSOSession creates a federated SSO session. POST /federation/sso/sessions.

func (*Client) CreateScimGroup added in v0.10.0 

func (c *Client) CreateScimGroup(ctx context.Context, g ScimGroup, callerToken string) (*ScimGroup, error)

CreateScimGroup provisions a SCIM group. POST /scim/v2/Groups.

func (*Client) CreateScimUser added in v0.10.0 

func (c *Client) CreateScimUser(ctx context.Context, u ScimUser, callerToken string) (*ScimUser, error)

CreateScimUser provisions a SCIM user. POST /scim/v2/Users.

func (*Client) CreateServiceAccount 

func (c *Client) CreateServiceAccount(ctx context.Context, req ServiceAccountCreate, callerToken string) (*ServiceAccountResponse, error)

CreateServiceAccount creates a service account (machine identity). POST /admin/users/create-service-account.

func (*Client) CreateTeam 

func (c *Client) CreateTeam(ctx context.Context, orgID string, req TeamCreate, callerToken string) (*Team, error)

CreateTeam creates a team in an organization (requires teams.write). POST /organizations/{org_id}/teams.

func (*Client) CreateTempAllowlist 

func (c *Client) CreateTempAllowlist(ctx context.Context, req TempAllowlistRequest, callerToken string) (*TempAllowlistCreateResponse, error)

CreateTempAllowlist adds a temporary IP allowlist entry. POST /network-policy/temp-allowlist.

func (*Client) DeactivateUser 

func (c *Client) DeactivateUser(ctx context.Context, userID, callerToken string) (*MessageDetailResponse, error)

DeactivateUser deactivates a user (requires users.write). POST /users/{user_id}/deactivate.

func (*Client) Delegate 

func (c *Client) Delegate(ctx context.Context, req DelegateTokenRequest, token string) (*TokenSet, error)

Delegate mints a delegated (act-as) token for the target user, scoped to the permissions the caller holds. POST /auth/delegate.

func (*Client) DeleteAPIKey 

func (c *Client) DeleteAPIKey(ctx context.Context, keyID, callerToken string) (*MessageResponse, error)

DeleteAPIKey revokes an API key. DELETE /api-keys/{key_id}.

func (*Client) DeleteAllRelationshipsForObject 

func (c *Client) DeleteAllRelationshipsForObject(ctx context.Context, storeID, objectType, objectID, token string) (int, error)

DeleteAllRelationshipsForObject removes EVERY tuple whose object == (objectType, objectID) — the generic cleanup primitive for deleting a resource or erasing its relationships. It is implemented client-side as a ListRelationships -> DeleteRelationships loop (there is no bulk server route today), deleting one tuple per call because the server's DELETE .../relationships accepts a SINGLE tuple. It re-lists from the start after draining a batch, so it is idempotent and safe to retry. Requires zanzibar.admin. Returns the total number of tuples deleted.

func (*Client) DeleteClientRegistration 

func (c *Client) DeleteClientRegistration(ctx context.Context, clientID string) error

DeleteClientRegistration deletes a dynamically-registered client. DELETE /auth/oauth/register/{client_id}.

func (*Client) DeleteCurrentUser 

func (c *Client) DeleteCurrentUser(ctx context.Context, confirmEmail, callerToken string) (*SelfDeleteResponse, error)

DeleteCurrentUser IRREVERSIBLY deletes the authenticated caller's own account. DELETE /users/me. Requires the caller's own bearer token; there is no admin/impersonation form of this call — a user may only delete themselves.

⚠️ THIS IS NOT UNDOABLE. Per the endpoint's own contract the server will: soft-delete the account and anonymize its PII, invalidate every session, hard-delete every API key, remove permissions, delegations and Zanzibar relationship tuples, drop organization and team memberships (flagging any organization left without an owner), clean up enterprise records, and emit an audit event.

confirmEmail must equal the caller's own account email exactly; a mismatch is rejected with no state change. Callers should obtain it from a deliberate user action (typing it), never auto-fill it from the session — auto-filling defeats the entire purpose of the guard.

func (*Client) DeleteEventSubscription 

func (c *Client) DeleteEventSubscription(ctx context.Context, subscriptionID, token string) error

DeleteEventSubscription deletes a webhook subscription. DELETE /events/subscriptions/{subscription_id}. Requires events.delete.

func (*Client) DeleteHRISConnection added in v0.10.0 

func (c *Client) DeleteHRISConnection(ctx context.Context, orgID, callerToken string) (*DeleteResult, error)

DeleteHRISConnection removes an org's HRIS connection. DELETE /organizations/{org_id}/hris/connection. Requires org.admin.

func (*Client) DeleteNetworkOverride 

func (c *Client) DeleteNetworkOverride(ctx context.Context, overrideID, callerToken string) (*NetworkPolicyStatusResponse, error)

DeleteNetworkOverride deletes an emergency override. DELETE /network-policy/overrides/{override_id}.

func (*Client) DeleteNetworkPolicy 

func (c *Client) DeleteNetworkPolicy(ctx context.Context, policyID, callerToken string) (*NetworkPolicyStatusResponse, error)

DeleteNetworkPolicy deletes a network policy. DELETE /network-policy/{policy_id}.

func (*Client) DeleteOrgEmailConfig 

func (c *Client) DeleteOrgEmailConfig(ctx context.Context, orgID, callerToken string) (*EmailConfigDeleteResponse, error)

DeleteOrgEmailConfig deletes an org's email configuration. DELETE /organizations/{org_id}/emails/config. Requires org.admin.

func (*Client) DeleteOrgEmailTemplate 

func (c *Client) DeleteOrgEmailTemplate(ctx context.Context, orgID, templateType, callerToken string) (*EmailTemplateDeleteResponse, error)

DeleteOrgEmailTemplate deletes one of an org's email templates. DELETE /organizations/{org_id}/emails/templates/{template_type}. Requires org.admin.

func (*Client) DeleteOrganization 

func (c *Client) DeleteOrganization(ctx context.Context, orgID, callerToken string) (*MessageResponse, error)

DeleteOrganization deletes an organization (requires org.admin). DELETE /organizations/{org_id}.

func (*Client) DeleteProvider 

func (c *Client) DeleteProvider(ctx context.Context, providerID, callerToken string) (*MessageResponse, error)

DeleteProvider deletes a provider config (requires org.admin). DELETE /providers/{provider_id}.

func (*Client) DeleteRelationshipByObject added in v0.10.0 

func (c *Client) DeleteRelationshipByObject(ctx context.Context, storeID, objectType, objectID, relation, subject, callerToken string) (*WriteOperationResponse, error)

DeleteRelationshipByObject deletes a single relationship named by its object path plus the relation/subject in the body. DELETE /zanzibar/stores/{store_id}/relationships/{object_type}/{object_id}.

func (*Client) DeleteRelationships 

func (c *Client) DeleteRelationships(ctx context.Context, storeID string, req RelationshipRequest, token string) (*WriteOperationResponse, error)

DeleteRelationships deletes a single relationship tuple (requires zanzibar.admin). DELETE /zanzibar/stores/{store_id}/relationships.

func (*Client) DeleteSAMLSP 

func (c *Client) DeleteSAMLSP(ctx context.Context, spID, callerToken string) (*EnterpriseMessageResponse, error)

DeleteSAMLSP deletes a service provider. DELETE /saml/sp/{sp_id}. Requires saml.admin / system.admin.

func (*Client) DeleteSCIMConnection added in v0.10.0 

func (c *Client) DeleteSCIMConnection(ctx context.Context, orgID, callerToken string) error

DeleteSCIMConnection disables SCIM provisioning for an org. DELETE /organizations/{org_id}/scim/connection. Requires org.admin.

func (*Client) DeleteSSODomain 

func (c *Client) DeleteSSODomain(ctx context.Context, domain, callerToken string) (*MessageResponse, error)

DeleteSSODomain removes an SSO domain config (requires org.admin). DELETE /federation/sso/domains/{domain}.

func (*Client) DeleteSSOSession 

func (c *Client) DeleteSSOSession(ctx context.Context, sessionID, token string) (*MessageResponse, error)

DeleteSSOSession terminates one of the caller's SSO sessions. DELETE /federation/sso/sessions/{session_id}.

func (*Client) DeleteScimGroup added in v0.10.0 

func (c *Client) DeleteScimGroup(ctx context.Context, id, callerToken string) error

DeleteScimGroup deletes a SCIM group. DELETE /scim/v2/Groups/{id} (204).

func (*Client) DeleteScimUser added in v0.10.0 

func (c *Client) DeleteScimUser(ctx context.Context, id, callerToken string) error

DeleteScimUser deprovisions a SCIM user. DELETE /scim/v2/Users/{id} (204).

func (*Client) DeleteTeam 

func (c *Client) DeleteTeam(ctx context.Context, teamID, callerToken string) (*MessageResponse, error)

DeleteTeam deletes a team (requires teams.write). DELETE /teams/{team_id}.

func (*Client) DeleteTempAllowlist 

func (c *Client) DeleteTempAllowlist(ctx context.Context, entryID, callerToken string) (*NetworkPolicyStatusResponse, error)

DeleteTempAllowlist removes a temporary allowlist entry. DELETE /network-policy/temp-allowlist/{entry_id}.

func (*Client) DeleteWebAuthnCredential 

func (c *Client) DeleteWebAuthnCredential(ctx context.Context, token, credentialID string) (*EnterpriseMessageResponse, error)

DeleteWebAuthnCredential removes one of the caller's credentials. DELETE /auth/passwordless/webauthn/credentials/{credential_id}.

func (*Client) Discover 

func (c *Client) Discover(ctx context.Context) (*ServiceDiscoveryResponse, error)

Discover fetches the service-discovery root. GET / (public).

func (*Client) DismissReport 

func (c *Client) DismissReport(ctx context.Context, reportID, callerToken string) (*LeakReportActionResponse, error)

DismissReport dismisses an abuse report. POST /reports/{report_id}/dismiss. Requires org.admin.

func (*Client) ElevatePrivileges 

func (c *Client) ElevatePrivileges(ctx context.Context, req ElevatePrivilegesRequest, callerToken string) (*ElevatePrivilegesResponse, error)

ElevatePrivileges grants elevated privileges to a user. POST /admin/users/elevate-privileges.

func (*Client) EmailHistory 

func (c *Client) EmailHistory(ctx context.Context, callerToken string) (*EmailHistoryResponse, error)

EmailHistory returns the system-wide sent-email history. GET /admin/emails/history. Requires system.admin.

func (*Client) EmailStats 

func (c *Client) EmailStats(ctx context.Context, callerToken string) (*EmailStatsResponse, error)

EmailStats returns system-wide email statistics. GET /admin/emails/stats. Requires system.admin.

func (*Client) EmailTemplateTypes 

func (c *Client) EmailTemplateTypes(ctx context.Context, callerToken string) (*TemplateTypesResponse, error)

EmailTemplateTypes lists the available email template types. GET /admin/emails/template-types. Requires system.admin.

func (*Client) EmergencyRevokeAPIKeys 

func (c *Client) EmergencyRevokeAPIKeys(ctx context.Context, req EmergencyRevokeRequest, callerToken string) (*EmergencyRevokeResponse, error)

EmergencyRevokeAPIKeys emergency-revokes API keys (requires org.admin). POST /admin/api-keys/emergency-revoke.

func (*Client) EnableSCIMConnection added in v0.10.0 

func (c *Client) EnableSCIMConnection(ctx context.Context, orgID, callerToken string) (*SCIMConnection, error)

EnableSCIMConnection enables SCIM provisioning for an org and returns the connection (including its bearer token). POST /organizations/{org_id}/scim/connection. Requires org.admin.

func (*Client) EnsureAuthorizationModel 

func (c *Client) EnsureAuthorizationModel(ctx context.Context, storeID string, model AuthorizationModel, callerToken string) (modelID string, changed bool, err error)

EnsureAuthorizationModel registers model only if the store's latest model is not already equivalent, and returns the effective (existing-or-newly-written) model id. It is idempotent and safe to run on every deploy: an unchanged model is a no-op (changed == false), a new or differing model is written (changed == true). Requires zanzibar.admin.

SERVER-GAP: this helper composes ReadAuthorizationModel + WriteAuthorizationModel, NEITHER of which exists in the auth service OpenAPI as of 2026-07-12 (no authorization-model management). Forward-looking; both underlying calls will 404 until the server implements model management.

func (*Client) EnterpriseHelp 

func (c *Client) EnterpriseHelp(ctx context.Context) (map[string]any, error)

EnterpriseHelp fetches the enterprise help payload. GET /help/enterprise (public).

func (*Client) EnterpriseLicense 

func (c *Client) EnterpriseLicense(ctx context.Context) (map[string]any, error)

EnterpriseLicense fetches the enterprise license payload. GET /enterprise/license (public).

func (*Client) EvaluateNetworkAccess added in v0.10.0 

func (c *Client) EvaluateNetworkAccess(ctx context.Context, callerToken string) (*AccessCheckResponse, error)

EvaluateNetworkAccess performs a network access-check via POST (same decision, POST form). POST /network-policy/access-check.

func (*Client) EvaluateNetworkPolicy 

func (c *Client) EvaluateNetworkPolicy(ctx context.Context, ip string) (*PolicyEvaluationResult, error)

EvaluateNetworkPolicy evaluates whether an IP is allowed (public). GET /network-policy/evaluate. ip is supplied as the `ip` query parameter.

func (*Client) EventSubscriptionStats 

func (c *Client) EventSubscriptionStats(ctx context.Context, subscriptionID, token string) (*EventSubscriptionStatsResponse, error)

EventSubscriptionStats returns delivery statistics for a subscription. GET /events/subscriptions/{subscription_id}/stats. Requires events.read.

func (*Client) EventTypes 

func (c *Client) EventTypes(ctx context.Context) (*EventTypesResponse, error)

EventTypes lists the available event types. GET /events/types (public).

func (*Client) FederationStats 

func (c *Client) FederationStats(ctx context.Context, callerToken string) (*FederationStatsResponse, error)

FederationStats returns federation usage statistics (requires system.admin). GET /federation/stats.

func (*Client) ForcePasswordReset 

func (c *Client) ForcePasswordReset(ctx context.Context, req ForcePasswordResetRequest, callerToken string) (*ForcePasswordResetResponse, error)

ForcePasswordReset forces password resets for users. POST /admin/password-policy/force-reset.

func (*Client) ForwardAuth 

func (c *Client) ForwardAuth(ctx context.Context, method, token string) (*ForwardAuthDecision, error)

ForwardAuth is the primary forward-auth decision endpoint. method may be GET, POST or HEAD. /forward-auth/.

func (*Client) ForwardAuthFail 

func (c *Client) ForwardAuthFail(ctx context.Context, method, token string) (*ForwardAuthDecision, error)

ForwardAuthFail is the explicit-fail decision endpoint. method may be GET, POST or HEAD. /forward-auth/fail.

func (*Client) ForwardAuthLive 

func (c *Client) ForwardAuthLive(ctx context.Context, method, token string) (*ForwardAuthDecision, error)

ForwardAuthLive is the liveness decision endpoint. method may be GET, POST or HEAD. /forward-auth/live.

func (*Client) ForwardAuthPass 

func (c *Client) ForwardAuthPass(ctx context.Context, method, token string) (*ForwardAuthDecision, error)

ForwardAuthPass is the explicit-pass decision endpoint. method may be GET, POST or HEAD. /forward-auth/pass.

func (*Client) GenerateRecoveryCodes 

func (c *Client) GenerateRecoveryCodes(ctx context.Context, token string) (*RecoveryCodesResponse, error)

GenerateRecoveryCodes generates a new set of MFA recovery codes for the caller. POST /auth/passwordless/recovery-codes/generate.

func (*Client) GenerateSAMLCertificate 

func (c *Client) GenerateSAMLCertificate(ctx context.Context, callerToken string) (*SAMLCertificateGenerateResponse, error)

GenerateSAMLCertificate generates a new SAML certificate. POST /saml/certificates/generate. Requires saml.admin / system.admin.

func (*Client) GenerateSigningKey 

func (c *Client) GenerateSigningKey(ctx context.Context, req KeyGenerationRequest, callerToken string) (*KeyGenerateResponse, error)

GenerateSigningKey generates a new signing key. POST /admin/jwks/generate.

func (*Client) GetAPIKey 

func (c *Client) GetAPIKey(ctx context.Context, keyID, token string) (*APIKey, error)

GetAPIKey fetches one API key's metadata. GET /api-keys/{key_id}.

func (*Client) GetClientRegistration 

func (c *Client) GetClientRegistration(ctx context.Context, clientID string) (*ClientRegistrationResponse, error)

GetClientRegistration reads a dynamically-registered client. GET /auth/oauth/register/{client_id}.

func (*Client) GetEventSubscription 

func (c *Client) GetEventSubscription(ctx context.Context, subscriptionID, token string) (*EventSubscription, error)

GetEventSubscription fetches a webhook subscription. GET /events/subscriptions/{subscription_id}. Requires events.read.

func (*Client) GetHRISConnection added in v0.10.0 

func (c *Client) GetHRISConnection(ctx context.Context, orgID, callerToken string) (*HRISConnectionStatus, error)

GetHRISConnection returns an org's HRIS connection status. GET /organizations/{org_id}/hris/connection.

func (*Client) GetHostedLoginPage 

func (c *Client) GetHostedLoginPage(ctx context.Context, slug string) (map[string]any, error)

GetHostedLoginPage fetches the hosted login page payload for a tenant slug. GET /login/{slug}. Returns the raw JSON the hosted page is rendered from.

func (*Client) GetInvitation added in v0.10.0 

func (c *Client) GetInvitation(ctx context.Context, orgID, invitationID, callerToken string) (*InvitationListItem, error)

GetInvitation fetches one pending invitation. GET /organizations/{org_id}/invitations/{invitation_id}.

func (*Client) GetJITConfig 

func (c *Client) GetJITConfig(ctx context.Context, callerToken string) (*JITConfigResponse, error)

GetJITConfig returns just-in-time provisioning config (requires org.admin). GET /federation/jit/config.

func (*Client) GetLoginConfig 

func (c *Client) GetLoginConfig(ctx context.Context, orgID, callerToken string) (*LoginConfigResponse, error)

GetLoginConfig returns a tenant's hosted-login configuration. GET /organizations/{org_id}/login-config.

func (*Client) GetMeshProvider 

func (c *Client) GetMeshProvider(ctx context.Context, serviceID, callerToken string) (*MeshProvider, error)

GetMeshProvider fetches one provider entry by its service id. GET /mesh/providers/{service_id}.

func (*Client) GetMyOrganizations 

func (c *Client) GetMyOrganizations(ctx context.Context, token string) ([]UserOrganizationInfo, error)

GetMyOrganizations lists organizations the token's user belongs to. GET /users/me/organizations.

func (*Client) GetMyProfile 

func (c *Client) GetMyProfile(ctx context.Context, token string) (*User, error)

GetMyProfile returns the caller's full profile. GET /users/me.

func (*Client) GetNamespace 

func (c *Client) GetNamespace(ctx context.Context, storeID, name, callerToken string) (*NamespaceDetailResponse, error)

GetNamespace fetches one namespace definition. GET /zanzibar/stores/{store_id}/namespaces/{namespace_name}.

func (*Client) GetNetworkPolicy 

func (c *Client) GetNetworkPolicy(ctx context.Context, policyID, callerToken string) (*NetworkPolicy, error)

GetNetworkPolicy fetches a network policy. GET /network-policy/{policy_id}.

func (*Client) GetOrgEmailConfig 

func (c *Client) GetOrgEmailConfig(ctx context.Context, orgID, callerToken string) (*OrgEmailConfigResponse, error)

GetOrgEmailConfig returns an org's email configuration. GET /organizations/{org_id}/emails/config. Requires org.admin.

func (*Client) GetOrgEmailTemplate 

func (c *Client) GetOrgEmailTemplate(ctx context.Context, orgID, templateType, callerToken string) (*OrgEmailTemplateResponse, error)

GetOrgEmailTemplate fetches one of an org's email templates. GET /organizations/{org_id}/emails/templates/{template_type}. Requires org.admin.

func (*Client) GetOrgHierarchy 

func (c *Client) GetOrgHierarchy(ctx context.Context, orgID, callerToken string) (*OrgHierarchyResponse, error)

GetOrgHierarchy returns the org's sub-tree. GET /organizations/{org_id}/hierarchy.

func (*Client) GetOrganization 

func (c *Client) GetOrganization(ctx context.Context, orgID, callerToken string) (*Organization, error)

GetOrganization fetches an organization/tenant. GET /organizations/{org_id}.

func (*Client) GetPasswordPolicy 

func (c *Client) GetPasswordPolicy(ctx context.Context, orgID, callerToken string) (*PasswordPolicyGetResponse, error)

GetPasswordPolicy fetches an org's password policy. GET /admin/password-policy/{org_id}.

func (*Client) GetProvider 

func (c *Client) GetProvider(ctx context.Context, providerID, callerToken string) (*Provider, error)

GetProvider fetches a provider config (requires org.read). GET /providers/{provider_id}.

func (*Client) GetPublicLoginConfig 

func (c *Client) GetPublicLoginConfig(ctx context.Context, slug string) (*PublicLoginConfig, error)

GetPublicLoginConfig returns the public login config for a tenant slug. GET /organizations/{slug}/login-config/public.

func (*Client) GetRoles 

func (c *Client) GetRoles(ctx context.Context, callerToken string) (map[string]RoleDefinition, error)

GetRoles returns the available roles and their permissions. GET /permissions/roles.

func (*Client) GetSAMLAttributeMappings 

func (c *Client) GetSAMLAttributeMappings(ctx context.Context, callerToken string) (*SAMLAttributeMappingResponse, error)

GetSAMLAttributeMappings returns the SAML attribute mappings. GET /saml/attributes/mappings. Requires saml.read / system.admin.

func (*Client) GetSAMLCertificates 

func (c *Client) GetSAMLCertificates(ctx context.Context, callerToken string) (*SAMLCertificateStatusResponse, error)

GetSAMLCertificates returns SAML certificate status. GET /saml/certificates. Requires saml.read / system.admin.

func (*Client) GetSAMLSP 

func (c *Client) GetSAMLSP(ctx context.Context, spID, callerToken string) (*SAMLSPDetailResponse, error)

GetSAMLSP fetches a service provider by id. GET /saml/sp/{sp_id}.

func (*Client) GetSCIMConnection added in v0.10.0 

func (c *Client) GetSCIMConnection(ctx context.Context, orgID, callerToken string) (*SCIMConnection, error)

GetSCIMConnection returns an org's SCIM provisioning connection. GET /organizations/{org_id}/scim/connection.

func (*Client) GetSSOConfig 

func (c *Client) GetSSOConfig(ctx context.Context, callerToken string) (*SSOConfigResponse, error)

GetSSOConfig returns the org SSO configuration (requires org.admin). GET /federation/sso/config.

func (*Client) GetSSODomain 

func (c *Client) GetSSODomain(ctx context.Context, domain, callerToken string) (*SSODomainConfigResponse, error)

GetSSODomain fetches one SSO domain config (requires org.admin). GET /federation/sso/domains/{domain}.

func (*Client) GetSSOSession 

func (c *Client) GetSSOSession(ctx context.Context, sessionID, token string) (*SSOSessionDetailResponse, error)

GetSSOSession fetches one of the caller's SSO sessions. GET /federation/sso/sessions/{session_id}.

func (*Client) GetScimGroup added in v0.10.0 

func (c *Client) GetScimGroup(ctx context.Context, id, callerToken string) (*ScimGroup, error)

GetScimGroup fetches one SCIM group. GET /scim/v2/Groups/{id}.

func (*Client) GetScimUser added in v0.10.0 

func (c *Client) GetScimUser(ctx context.Context, id, callerToken string) (*ScimUser, error)

GetScimUser fetches one SCIM user. GET /scim/v2/Users/{id}.

func (*Client) GetTeam 

func (c *Client) GetTeam(ctx context.Context, teamID, callerToken string) (*Team, error)

GetTeam fetches a team by id (requires teams.read). GET /teams/{team_id}.

func (*Client) GetTeamPermissions 

func (c *Client) GetTeamPermissions(ctx context.Context, teamID, callerToken string) (*TeamPermissionsResponse, error)

GetTeamPermissions returns a team's effective permissions (requires teams.read). GET /teams/{team_id}/permissions.

func (*Client) GetUser 

func (c *Client) GetUser(ctx context.Context, userID, callerToken string) (*User, error)

GetUser fetches a user by id. GET /users/{user_id}. callerToken may be a user JWT or "" to use the service API key.

func (*Client) GetUserPermissions 

func (c *Client) GetUserPermissions(ctx context.Context, userID, callerToken string) (*UserPermissions, error)

GetUserPermissions lists a user's effective permissions. GET /permissions/user/{user_id}.

func (*Client) GlobalEmailConfig 

func (c *Client) GlobalEmailConfig(ctx context.Context, callerToken string) (*GlobalEmailConfigResponse, error)

GlobalEmailConfig returns the system-wide email configuration. GET /admin/emails/config. Requires system.admin.

func (*Client) GrantDelegation 

func (c *Client) GrantDelegation(ctx context.Context, req DelegationGrant, token string) (*DelegationResponse, error)

GrantDelegation grants act-as rights to an actor (you can only delegate permissions you hold). POST /delegation/grant.

func (*Client) GrantPermission 

func (c *Client) GrantPermission(ctx context.Context, userID, orgID, permission, callerToken string) (*MessageResponse, error)

GrantPermission grants an explicit permission to a user. POST /permissions/grant. Requires org.admin / users.write (or api.*).

Per the auth service OpenAPI (verified 2026-07-12) this endpoint takes its arguments as REQUIRED query parameters (user_id, org_id, permission), NOT a request body.

func (*Client) Health 

func (c *Client) Health(ctx context.Context) (*HealthCheckResponse, error)

Health returns the service health check. GET /health (public).

func (*Client) Help 

func (c *Client) Help(ctx context.Context) (map[string]any, error)

Help fetches the API help payload. GET /help (public).

func (*Client) Introspect 

func (c *Client) Introspect(ctx context.Context, token, hint string) (*Introspection, error)

Introspect performs RFC 7662 token introspection. POST /token/introspect. hint may be "" or "access_token"/"refresh_token". Always check Active.

func (*Client) InvalidateValidation added in v0.10.0 

func (c *Client) InvalidateValidation(cred string)

InvalidateValidation drops every cached decision for one credential, across every request shape it was validated under.

Use it the moment this process learns a credential is no longer good — it revoked the key itself, it handled a revocation webhook, a user logged out. That turns the TTL into a bound on how long an UNNOTICED revocation lingers, rather than a bound on every revocation.

func (*Client) InviteToOrganization 

func (c *Client) InviteToOrganization(ctx context.Context, orgID string, req OrganizationInvite, callerToken string) (*MessageResponse, error)

InviteToOrganization invites a user by email (requires users.invite). POST /organizations/{org_id}/invite.

func (*Client) JWKS 

func (c *Client) JWKS(ctx context.Context) (JWKS, error)

JWKS returns the service's signing key set, using a TTL cache (10m) with single-flight refresh. GET /.well-known/jwks.json. Use RefreshJWKS to force a fetch (e.g. on an unknown kid).

func (*Client) JWKSHealth 

func (c *Client) JWKSHealth(ctx context.Context) (map[string]any, error)

JWKSHealth reports the health of the global JWKS endpoint. GET /.well-known/jwks.json/health.

func (*Client) JWKSHealthDetail 

func (c *Client) JWKSHealthDetail(ctx context.Context) (*JwksHealthResponse, error)

JWKSHealthDetail returns JWKS health detail. GET /health/jwks (public).

func (*Client) JWKSMetrics 

func (c *Client) JWKSMetrics(ctx context.Context, callerToken string) (*JwksMetricsResponse, error)

JWKSMetrics returns JWKS operational metrics. GET /metrics/jwks. Requires admin.jwks.read / jwks.read.

func (*Client) JWKSNextRotation 

func (c *Client) JWKSNextRotation(ctx context.Context, callerToken string) (*NextRotationResponse, error)

JWKSNextRotation returns the next scheduled rotation. GET /admin/jwks/next-rotation.

func (*Client) JWKSRotationStatus 

func (c *Client) JWKSRotationStatus(ctx context.Context, callerToken string) (*RotationStatusResponse, error)

JWKSRotationStatus returns current rotation status. GET /admin/jwks/rotation-status.

func (*Client) ListAPIKeys 

func (c *Client) ListAPIKeys(ctx context.Context, callerToken string) ([]APIKey, error)

ListAPIKeys lists the caller's API keys. GET /api-keys/. 

func (c *Client) ListActiveMagicLinks(ctx context.Context, token string) (*ActiveMagicLinksResponse, error)

ListActiveMagicLinks lists the caller's outstanding magic links. GET /auth/passwordless/magic-link/active.

func (*Client) ListAttributeMappings 

func (c *Client) ListAttributeMappings(ctx context.Context, callerToken string) (*AttributeMappingListResponse, error)

ListAttributeMappings lists federation attribute mappings (requires system.admin). GET /federation/attribute-mappings.

func (*Client) ListAuthorizationModels 

func (c *Client) ListAuthorizationModels(ctx context.Context, storeID, pageToken, callerToken string) (*ListAuthorizationModelsResponse, error)

ListAuthorizationModels lists a store's model versions (newest first). Pass pageToken == "" for the first page and the response's ContinuationToken to continue. GET /zanzibar/stores/{store_id}/authorization-models.

SERVER-GAP: this endpoint does NOT exist in the auth service OpenAPI as of 2026-07-12 (no authorization-model management). Forward-looking; will 404 until the server implements it.

func (*Client) ListDelegations 

func (c *Client) ListDelegations(ctx context.Context, userID, token string) ([]DelegationEntry, error)

ListDelegations lists a user's delegations (own unless admin). GET /delegation/list/{user_id}.

func (*Client) ListDevices 

func (c *Client) ListDevices(ctx context.Context, token string) (*DeviceListResponse, error)

ListDevices lists the caller's known passwordless devices. GET /auth/passwordless/devices.

func (*Client) ListEventSubscriptions 

func (c *Client) ListEventSubscriptions(ctx context.Context, token string) (*EventSubscriptionListResponse, error)

ListEventSubscriptions lists webhook subscriptions. GET /events/subscriptions. Requires events.read.

func (*Client) ListInvitations 

func (c *Client) ListInvitations(ctx context.Context, orgID, callerToken string) ([]InvitationListItem, error)

ListInvitations lists pending invitations. GET /organizations/{org_id}/invitations.

func (*Client) ListMeshProviders 

func (c *Client) ListMeshProviders(ctx context.Context, q url.Values, callerToken string) (*MeshProvidersListResponse, error)

ListMeshProviders lists providers in the mesh directory. GET /mesh/providers. Pass an empty callerToken for the public directory.

q may carry server-supported filters; pass nil for none.

func (*Client) ListNamespaces 

func (c *Client) ListNamespaces(ctx context.Context, storeID, callerToken string) (*NamespaceListResponse, error)

ListNamespaces lists namespaces in a store. GET /zanzibar/stores/{store_id}/namespaces.

func (*Client) ListNetworkOverrides 

func (c *Client) ListNetworkOverrides(ctx context.Context, callerToken string) (*OverrideListResponse, error)

ListNetworkOverrides lists emergency overrides. GET /network-policy/overrides.

func (*Client) ListNetworkPolicies 

func (c *Client) ListNetworkPolicies(ctx context.Context, callerToken string) (*NetworkPolicyListResponse, error)

ListNetworkPolicies lists network policies. GET /network-policy/.

func (*Client) ListNetworkViolations 

func (c *Client) ListNetworkViolations(ctx context.Context, callerToken string) (*ViolationListResponse, error)

ListNetworkViolations lists recorded access violations. GET /network-policy/violations.

func (*Client) ListObjectsPaged 

func (c *Client) ListObjectsPaged(ctx context.Context, storeID string, req ListObjectsRequest, callerToken string) (*ListObjectsResponse, error)

ListObjectsPaged lists the object ids a subject relates to. Set req.MaxResults (1..1000) to cap the result set. POST /zanzibar/stores/{store_id}/list-objects.

SERVER-GAP (pagination): the route is REAL, but the auth service OpenAPI (verified 2026-07-12) caps results with `max_results` and has NO request-side continuation token. The response's ContinuationToken is documented as "reserved for future use" and currently always empty, so this method returns at most one (capped) page. It is retained as an alias of ZanzibarListObjects for callers that want the pagination-shaped name.

func (*Client) ListOrgClients 

func (c *Client) ListOrgClients(ctx context.Context, orgID, callerToken string) (*OrgClientSafeResponse, error)

ListOrgClients lists the OAuth clients registered for a tenant (safe view). GET /organizations/{org_id}/clients.

func (*Client) ListOrgEmailTemplates 

func (c *Client) ListOrgEmailTemplates(ctx context.Context, orgID, callerToken string) (*OrgEmailTemplateResponse, error)

ListOrgEmailTemplates lists an org's email templates. GET /organizations/{org_id}/emails/templates. Requires org.admin.

func (*Client) ListOrgSessions 

func (c *Client) ListOrgSessions(ctx context.Context, orgID, callerToken string) (*OrgSessionsResponse, error)

ListOrgSessions lists active sessions in an organization. GET /organizations/{org_id}/sessions.

func (*Client) ListOrgUsers 

func (c *Client) ListOrgUsers(ctx context.Context, orgID, callerToken string) (*OrgUserResponse, error)

ListOrgUsers lists members of an organization (requires users.read). GET /organizations/{org_id}/users.

func (*Client) ListProviders 

func (c *Client) ListProviders(ctx context.Context, callerToken string) ([]Provider, error)

ListProviders lists configured providers (requires org.read). GET /providers/.

func (*Client) ListRegisteredServices 

func (c *Client) ListRegisteredServices(ctx context.Context, callerToken string) (*RegisteredServicesResponse, error)

ListRegisteredServices lists services that have registered permissions. GET /permissions/registry/services.

func (*Client) ListRelationships 

func (c *Client) ListRelationships(ctx context.Context, storeID, objectType, objectID, relation, callerToken string) (*RelationshipsResponse, error)

ListRelationships lists the tuples for an object, optionally filtered by relation (pass "" for all). GET /zanzibar/stores/{store_id}/relationships/{object_type}/{object_id}.

func (*Client) ListRelationshipsPaged 

func (c *Client) ListRelationshipsPaged(ctx context.Context, storeID, objectType, objectID, relation, callerToken string) (*RelationshipsPage, error)

ListRelationshipsPaged lists the tuples whose object == (objectType, objectID), optionally filtered by relation (pass "" for all). GET /zanzibar/stores/{store_id}/relationships/{object_type}/{object_id}.

SERVER-GAP (pagination): the auth service OpenAPI (verified 2026-07-12) accepts ONLY a `relation` query filter on this route — it does NOT accept page_size/continuation_token and returns the FULL (unpaged) result set {object, relationships:[]RelationshipEntry} with no cursor. This method is therefore a thin wrapper over ListRelationships; RelationshipsPage's ContinuationToken is always empty.

func (*Client) ListReports 

func (c *Client) ListReports(ctx context.Context, callerToken string) (*LeakReportListResponse, error)

ListReports lists abuse/leak reports. GET /reports. Requires org.admin.

func (*Client) ListRevokedKeys 

func (c *Client) ListRevokedKeys(ctx context.Context, callerToken string) (*RevokedKeysListResponse, error)

ListRevokedKeys lists revoked signing keys. GET /admin/jwks/revoked.

func (*Client) ListSAMLSPs 

func (c *Client) ListSAMLSPs(ctx context.Context, callerToken string) (*SAMLSPListResponse, error)

ListSAMLSPs lists registered service providers. GET /saml/sp/list. Requires saml.read.

func (*Client) ListSAMLSessions 

func (c *Client) ListSAMLSessions(ctx context.Context, token string) (*SAMLSessionListResponse, error)

ListSAMLSessions lists the caller's active SAML sessions. GET /saml/sessions.

func (*Client) ListSSODomains 

func (c *Client) ListSSODomains(ctx context.Context, callerToken string) (*SSODomainListResponse, error)

ListSSODomains lists configured SSO domains (requires org.admin). GET /federation/sso/domains.

func (*Client) ListSSOSessions 

func (c *Client) ListSSOSessions(ctx context.Context, token string) (*SSOSessionListResponse, error)

ListSSOSessions lists the caller's federated SSO sessions. GET /federation/sso/sessions.

func (*Client) ListScimGroups added in v0.10.0 

func (c *Client) ListScimGroups(ctx context.Context, callerToken string) (*ScimListResponse, error)

ListScimGroups lists SCIM groups. GET /scim/v2/Groups.

func (*Client) ListScimUsers added in v0.10.0 

func (c *Client) ListScimUsers(ctx context.Context, callerToken string) (*ScimListResponse, error)

ListScimUsers lists SCIM users. GET /scim/v2/Users.

func (*Client) ListTeamMembers 

func (c *Client) ListTeamMembers(ctx context.Context, teamID, callerToken string) ([]TeamMember, error)

ListTeamMembers lists a team's members (requires teams.read). GET /teams/{team_id}/members.

func (*Client) ListTeams 

func (c *Client) ListTeams(ctx context.Context, orgID, callerToken string) ([]Team, error)

ListTeams lists teams in an organization (requires teams.read). GET /organizations/{org_id}/teams.

func (*Client) ListTempAllowlist 

func (c *Client) ListTempAllowlist(ctx context.Context, callerToken string) (*TempAllowlistListResponse, error)

ListTempAllowlist lists temporary allowlist entries. GET /network-policy/temp-allowlist.

func (*Client) ListValidPermissions 

func (c *Client) ListValidPermissions(ctx context.Context) (*ValidPermissionsResponse, error)

ListValidPermissions returns all permission strings the registry knows about. GET /permissions/registry/valid-permissions. PUBLIC.

func (*Client) ListWebAuthnCredentials 

func (c *Client) ListWebAuthnCredentials(ctx context.Context, token string) (*WebAuthnCredentialListResponse, error)

ListWebAuthnCredentials lists the caller's registered credentials. GET /auth/passwordless/webauthn/credentials.

func (*Client) Login 

func (c *Client) Login(ctx context.Context, req LoginRequest) (*TokenSet, error)

Login authenticates a user and returns a token set. POST /auth/login.

func (*Client) Logout 

func (c *Client) Logout(ctx context.Context, token string) (*LogoutResult, error)

Logout invalidates the session for the given user token. POST /auth/logout.

func (*Client) MagicLinkAnalytics 

func (c *Client) MagicLinkAnalytics(ctx context.Context, token string) (*MagicLinkAnalyticsResponse, error)

MagicLinkAnalytics returns magic-link usage analytics for the caller. GET /auth/passwordless/magic-link/analytics.

func (*Client) MagicLinkConfig 

func (c *Client) MagicLinkConfig(ctx context.Context) (*MagicLinkConfigResponse, error)

MagicLinkConfig returns the magic-link configuration. GET /auth/passwordless/magic-link/config.

func (*Client) Me 

func (c *Client) Me(ctx context.Context, token string) (*User, error)

Me returns the current user for a token. GET /auth/me.

func (*Client) Metrics 

func (c *Client) Metrics(ctx context.Context, callerToken string) (map[string]any, error)

Metrics fetches the service metrics payload. GET /metrics. Requires admin.metrics.read / metrics.read.

func (*Client) MigratePermissions 

func (c *Client) MigratePermissions(ctx context.Context, storeID, userID string, permissions []string, callerToken string) (*ZanzibarMessageResponse, error)

MigratePermissions migrates a user's legacy RBAC permissions into Zanzibar tuples (requires zanzibar.admin). The user id and permission list are passed as `user_id` and repeated `permissions` query parameters (required by the server). POST /zanzibar/stores/{store_id}/migrate/permissions.

func (*Client) MigrateSetupDefaults 

func (c *Client) MigrateSetupDefaults(ctx context.Context, storeID, callerToken string) (*ZanzibarMessageResponse, error)

MigrateSetupDefaults installs default namespaces/relations (requires zanzibar.admin). POST /zanzibar/stores/{store_id}/migrate/setup-defaults.

func (*Client) MyQuotaUsage 

func (c *Client) MyQuotaUsage(ctx context.Context, token string) (*QuotaUsageResponse, error)

MyQuotaUsage returns the caller's quota usage. GET /quotas/my-usage.

func (*Client) NetworkAccessCheck added in v0.10.0 

func (c *Client) NetworkAccessCheck(ctx context.Context, callerToken string) (*AccessCheckResponse, error)

NetworkAccessCheck reports how network policy applies to the caller's current request (IP/zone/enforcement). GET /network-policy/access-check.

func (*Client) OAuthAuthorize 

func (c *Client) OAuthAuthorize(ctx context.Context, token string, params url.Values) (*AuthorizationResponse, error)

OAuthAuthorize starts the interactive OAuth2 authorization flow for the current user. GET /auth/authorize. params are appended as query parameters. (The token-validation route-gating primitive is the separate Authorize method.)

func (*Client) OAuthAuthorizeURL 

func (c *Client) OAuthAuthorizeURL(ctx context.Context, p OAuthAuthorizeParams) (*OAuthAuthorize, error)

OAuthAuthorizeURL starts an OAuth2/OIDC authorization flow with the given provider and returns the authorization URL the user-agent should be redirected to. GET /auth/oauth/{provider}/authorize.

func (*Client) OAuthCallback 

func (c *Client) OAuthCallback(ctx context.Context, p OAuthCallbackParams) (*TokenSet, error)

OAuthCallback completes an OAuth2/OIDC flow by exchanging the authorization code returned by the IdP for a token set. POST /auth/oauth/{provider}/callback.

func (*Client) OAuthToken 

func (c *Client) OAuthToken(ctx context.Context, form url.Values) (*TokenResponse, error)

OAuthToken exchanges credentials at the OAuth2 token endpoint. This is the device/CLI grant path (authorization_code, refresh_token, etc.). POST /auth/oauth/token (form-encoded).

func (*Client) OpenIDConfiguration 

func (c *Client) OpenIDConfiguration(ctx context.Context) (*OpenIDConfiguration, error)

OpenIDConfiguration fetches the OIDC discovery document. GET /.well-known/openid-configuration.

func (*Client) OrgAuthProviders 

func (c *Client) OrgAuthProviders(ctx context.Context, slug string) (*OrgProvidersResponse, error)

OrgAuthProviders lists the tenant's safe provider metadata for a hosted login page. GET /organizations/{slug}/auth/providers.

func (*Client) OrgEmailHistory 

func (c *Client) OrgEmailHistory(ctx context.Context, orgID, callerToken string) (*EmailHistoryResponse, error)

OrgEmailHistory returns an org's sent-email history. GET /organizations/{org_id}/emails/history. Requires org.admin.

func (*Client) OrgJWKS 

func (c *Client) OrgJWKS(ctx context.Context, orgID string) (JWKS, error)

OrgJWKS returns an organization's signing key set, cached per org. GET /organizations/{org_id}/.well-known/jwks.json.

func (*Client) OrgLogin 

func (c *Client) OrgLogin(ctx context.Context, slug string, req OrgLoginRequest) (*TokenSet, error)

OrgLogin authenticates a user against a specific tenant's login endpoint. POST /organizations/{slug}/auth/login.

func (*Client) OrgLogout 

func (c *Client) OrgLogout(ctx context.Context, slug, token string) (*HostedLoginMessageResponse, error)

OrgLogout logs out of a tenant session. POST /organizations/{slug}/auth/logout.

func (*Client) OrgRefresh 

func (c *Client) OrgRefresh(ctx context.Context, slug, refreshToken string) (*TokenResponse, error)

OrgRefresh refreshes a token against a tenant's refresh endpoint. POST /organizations/{slug}/auth/refresh.

func (*Client) OrgRegister 

func (c *Client) OrgRegister(ctx context.Context, slug string, req OrgRegisterRequest) (*TokenSet, error)

OrgRegister creates a user within a specific tenant. POST /organizations/{slug}/auth/register.

func (*Client) OrgResetPassword 

func (c *Client) OrgResetPassword(ctx context.Context, slug string, req OrgPasswordResetRequest) (*HostedLoginMessageResponse, error)

OrgResetPassword requests a password reset within a tenant. POST /organizations/{slug}/auth/reset-password.

func (*Client) OrgSSOCallback 

func (c *Client) OrgSSOCallback(ctx context.Context, slug string, form url.Values) (map[string]any, error)

OrgSSOCallback completes an org-scoped SSO flow (form-encoded callback). POST /organizations/{slug}/auth/sso/callback.

func (*Client) OrgSSOInitiate 

func (c *Client) OrgSSOInitiate(ctx context.Context, slug string, params url.Values) (map[string]any, error)

OrgSSOInitiate begins an org-scoped SSO flow, returning the redirect target. GET /organizations/{slug}/auth/sso/initiate.

func (*Client) OrgToken 

func (c *Client) OrgToken(ctx context.Context, slug string, form url.Values) (*TokenResponse, error)

OrgToken exchanges credentials at a tenant's token endpoint (form-encoded). POST /organizations/{slug}/auth/token.

func (*Client) PasswordAuditEvents 

func (c *Client) PasswordAuditEvents(ctx context.Context, callerToken string) (*PasswordAuditEventsResponse, error)

PasswordAuditEvents returns password-related audit events. GET /admin/audit/password-events.

func (*Client) PasswordComplianceReport 

func (c *Client) PasswordComplianceReport(ctx context.Context, callerToken string) (*PasswordComplianceResponse, error)

PasswordComplianceReport returns password-compliance stats. GET /admin/reports/password-compliance.

func (*Client) PatchScimGroup added in v0.10.0 

func (c *Client) PatchScimGroup(ctx context.Context, id string, req ScimPatchRequest, callerToken string) (*ScimGroup, error)

PatchScimGroup applies a SCIM PatchOp to a group. PATCH /scim/v2/Groups/{id}.

func (*Client) PatchScimUser added in v0.10.0 

func (c *Client) PatchScimUser(ctx context.Context, id string, req ScimPatchRequest, callerToken string) (*ScimUser, error)

PatchScimUser applies a SCIM PatchOp to a user. PATCH /scim/v2/Users/{id}.

func (*Client) PreviewOrgEmailTemplate 

func (c *Client) PreviewOrgEmailTemplate(ctx context.Context, orgID, templateType string, vars map[string]any, callerToken string) (*TemplatePreviewResponse, error)

PreviewOrgEmailTemplate renders a preview of an org's email template. POST /organizations/{org_id}/emails/templates/{template_type}/preview. Requires org.admin.

func (*Client) PropagateLogout 

func (c *Client) PropagateLogout(ctx context.Context, token string) (*LogoutPropagationResponse, error)

PropagateLogout propagates a logout across federated domains. POST /federation/sso/propagate-logout.

func (*Client) PropagateSSO 

func (c *Client) PropagateSSO(ctx context.Context, callerToken string) (*SSOPropagateResponse, error)

PropagateSSO propagates an SSO session across domains (requires sso.admin). POST /federation/sso/propagate.

func (*Client) ProviderAuthorizeInfo 

func (c *Client) ProviderAuthorizeInfo(ctx context.Context, provider string, params url.Values) (*OAuthProviderAuthorizeResponse, error)

ProviderAuthorizeInfo returns provider authorize metadata for a programmatic device/CLI flow. GET /auth/oauth/{provider}/authorize. Unlike OAuthAuthorizeURL this returns the typed discovery payload directly.

func (*Client) PublishMeshProvider 

func (c *Client) PublishMeshProvider(ctx context.Context, req MeshProviderPublishRequest, callerToken string) (*MeshProviderPublishResponse, error)

PublishMeshProvider publishes (or updates) this service's mesh directory entry. POST /mesh/providers.

Check the returned Valid and Listed fields: a nil error means the request was accepted, NOT that the provider is listed.

func (*Client) PushedAuthorizationRequest 

func (c *Client) PushedAuthorizationRequest(ctx context.Context, params url.Values) (*PushedAuthorizationResponse, error)

PushedAuthorizationRequest performs an RFC 9126 PAR, registering the authorization parameters and returning a request_uri. POST /auth/oauth/par.

func (*Client) QuotaTiers 

func (c *Client) QuotaTiers(ctx context.Context) (*QuotaTiersResponse, error)

QuotaTiers lists the available subscription tiers. GET /quotas/tiers (public).

func (*Client) ReadAuthorizationModel 

func (c *Client) ReadAuthorizationModel(ctx context.Context, storeID, modelID, callerToken string) (*AuthorizationModelResponse, error)

ReadAuthorizationModel fetches a single model version. Pass modelID == "" (or "latest") to read the store's latest model. GET /zanzibar/stores/{store_id}/authorization-models/{authorization_model_id}.

SERVER-GAP: this endpoint does NOT exist in the auth service OpenAPI as of 2026-07-12 (no authorization-model management). Forward-looking; will 404 until the server implements it.

func (*Client) RecentAlerts 

func (c *Client) RecentAlerts(ctx context.Context, callerToken string) (*RecentAlertsResponse, error)

RecentAlerts returns recent operational alerts. GET /metrics/alerts/recent. Requires admin.jwks.read / jwks.read.

func (*Client) RecoverJWKS 

func (c *Client) RecoverJWKS(ctx context.Context) (*JwksRecoverResponse, error)

RecoverJWKS triggers JWKS recovery. POST /health/jwks/recover (public).

func (*Client) Refresh 

func (c *Client) Refresh(ctx context.Context, refreshToken string) (*TokenSet, error)

Refresh exchanges a refresh token for a new token set. POST /auth/refresh.

func (*Client) RefreshJWKS 

func (c *Client) RefreshJWKS(ctx context.Context) (JWKS, error)

RefreshJWKS forces a refetch of the global key set, bypassing the cache.

func (*Client) RefreshTokenForm 

func (c *Client) RefreshTokenForm(ctx context.Context, refreshToken string) (*TokenResponse, error)

RefreshTokenForm exchanges a refresh token via the form-encoded token endpoint. POST /token/refresh.

func (*Client) Register 

func (c *Client) Register(ctx context.Context, req RegisterRequest) (*TokenSet, error)

Register creates a new user and returns a token set. POST /auth/register.

func (*Client) RegisterClient 

func (c *Client) RegisterClient(ctx context.Context, req ClientRegistration) (*ClientRegistrationResponse, error)

RegisterClient performs RFC 7591 dynamic client registration. POST /auth/oauth/register.

func (*Client) RegisterSAMLSP 

func (c *Client) RegisterSAMLSP(ctx context.Context, req SAMLServiceProviderConfig, callerToken string) (*SAMLSPRegistrationResponse, error)

RegisterSAMLSP registers a SAML service provider. POST /saml/sp/register. Requires saml.admin. callerToken may be a JWT or an API key.

func (*Client) RegisterServicePermissions 

func (c *Client) RegisterServicePermissions(ctx context.Context, req ServicePermissionRegister, callerToken string) (*ServicePermissionResponse, error)

RegisterServicePermissions registers a service's permission vocabulary. POST /permissions/registry/register. Requires permissions.register.

func (*Client) RegistryStats 

func (c *Client) RegistryStats(ctx context.Context) (*RegistryStatsResponse, error)

RegistryStats returns aggregate permission-registry counters. GET /permissions/registry/stats. PUBLIC.

func (*Client) RemoveOrgUser 

func (c *Client) RemoveOrgUser(ctx context.Context, orgID, userID, callerToken string) (*MessageResponse, error)

RemoveOrgUser removes a member from an organization (requires users.write). DELETE /organizations/{org_id}/users/{user_id}.

func (*Client) RemoveTeamMember 

func (c *Client) RemoveTeamMember(ctx context.Context, teamID, userID, callerToken string) (*MessageResponse, error)

RemoveTeamMember removes a member from a team (requires teams.write). DELETE /teams/{team_id}/members/{user_id}.

func (*Client) ReplaceScimGroup added in v0.10.0 

func (c *Client) ReplaceScimGroup(ctx context.Context, id string, g ScimGroup, callerToken string) (*ScimGroup, error)

ReplaceScimGroup replaces a SCIM group. PUT /scim/v2/Groups/{id}.

func (*Client) ReplaceScimUser added in v0.10.0 

func (c *Client) ReplaceScimUser(ctx context.Context, id string, u ScimUser, callerToken string) (*ScimUser, error)

ReplaceScimUser replaces a SCIM user (PUT semantics). PUT /scim/v2/Users/{id}.

func (*Client) RequestPasswordReset 

func (c *Client) RequestPasswordReset(ctx context.Context, req PasswordReset) (*PasswordResetResponse, error)

RequestPasswordReset starts a password-reset flow (sends an email). POST /users/request-password-reset. PUBLIC.

func (*Client) RequestPasswordResetAuth 

func (c *Client) RequestPasswordResetAuth(ctx context.Context, req PasswordReset) (*PasswordResetResponse, error)

RequestPasswordResetAuth requests a password reset via the auth endpoint. POST /auth/password-reset.

func (*Client) ResetAllCircuitBreakers 

func (c *Client) ResetAllCircuitBreakers(ctx context.Context, callerToken string) (*CircuitBreakerResetAllResponse, error)

ResetAllCircuitBreakers resets all circuit breakers. POST /admin/circuit-breakers/reset-all.

func (*Client) ResetCircuitBreaker 

func (c *Client) ResetCircuitBreaker(ctx context.Context, name, callerToken string) (*CircuitBreakerResetResponse, error)

ResetCircuitBreaker resets one circuit breaker. POST /admin/circuit-breakers/{breaker_name}/reset.

func (*Client) ResetPassword 

func (c *Client) ResetPassword(ctx context.Context, req PasswordResetConfirm) (*PasswordResetConfirmResponse, error)

ResetPassword completes a password-reset flow with a token. POST /users/reset-password. PUBLIC.

func (*Client) ResetValidationCache added in v0.10.0 

func (c *Client) ResetValidationCache()

ResetValidationCache drops every cached decision. Intended for tests and for a deliberate "trust nothing" reset; ordinary revocation should use InvalidateValidation, which does not punish every other credential.

func (*Client) ResolveReport 

func (c *Client) ResolveReport(ctx context.Context, reportID, callerToken string) (*LeakReportActionResponse, error)

ResolveReport resolves an abuse report. POST /reports/{report_id}/resolve. Requires org.admin.

func (*Client) RevocationAuditLog 

func (c *Client) RevocationAuditLog(ctx context.Context, callerToken string) ([]RevocationAuditEntry, error)

RevocationAuditLog lists revocation audit entries. GET /admin/audit/revocations.

func (*Client) RevokeDelegation 

func (c *Client) RevokeDelegation(ctx context.Context, actorID, token string) (*MessageResponse, error)

RevokeDelegation revokes an actor's delegation. DELETE /delegation/revoke/{actor_id}.

func (*Client) RevokeInvitation 

func (c *Client) RevokeInvitation(ctx context.Context, orgID, invitationID, callerToken string) (*MessageResponse, error)

RevokeInvitation cancels a pending invitation. DELETE /organizations/{org_id}/invitations/{invitation_id}. 

func (c *Client) RevokeMagicLink(ctx context.Context, callerToken, linkToken string) (*EnterpriseMessageResponse, error)

RevokeMagicLink revokes a specific magic link by token. DELETE /auth/passwordless/magic-link/{token}.

func (*Client) RevokeOrgSessions 

func (c *Client) RevokeOrgSessions(ctx context.Context, orgID, callerToken string) (*MessageResponse, error)

RevokeOrgSessions revokes ALL sessions in an organization (requires org.admin). DELETE /organizations/{org_id}/sessions.

func (*Client) RevokePermission 

func (c *Client) RevokePermission(ctx context.Context, userID, orgID, permission, callerToken string) (*MessageResponse, error)

RevokePermission revokes an explicitly-granted permission (not role-inherited). POST /permissions/revoke. Requires users.write. Like GrantPermission, the server reads user_id, org_id and permission from REQUIRED query parameters.

func (*Client) RevokeSigningKey 

func (c *Client) RevokeSigningKey(ctx context.Context, kid string, req KeyRevocationRequest, callerToken string) (*KeyRevocationResponse, error)

RevokeSigningKey revokes a signing key by kid. POST /admin/jwks/revoke/{kid}.

func (*Client) RevokeToken 

func (c *Client) RevokeToken(ctx context.Context, callerToken, tokenToRevoke, hint string) (*RevokeResult, error)

RevokeToken revokes a user-issued access or refresh token. POST /auth/revoke. The token to revoke is supplied in the body; the caller's own bearer token (callerToken) authenticates the request.

func (*Client) RevokeTokenPublic 

func (c *Client) RevokeTokenPublic(ctx context.Context, token, hint string) error

RevokeTokenPublic revokes a token via the RFC 7009 public endpoint POST /token/revoke (form-encoded, no caller auth required).

func (*Client) RevokeUserSessions 

func (c *Client) RevokeUserSessions(ctx context.Context, orgID, userID, callerToken string) (*SessionRevokeResponse, error)

RevokeUserSessions revokes a single user's sessions (requires org.admin). DELETE /organizations/{org_id}/users/{user_id}/sessions.

func (*Client) RotateSigningKeys 

func (c *Client) RotateSigningKeys(ctx context.Context, req KeyRotationRequest, callerToken string) (*KeyRotationResponse, error)

RotateSigningKeys rotates the signing key set. POST /admin/jwks/rotate.

func (*Client) SAMLAnalytics 

func (c *Client) SAMLAnalytics(ctx context.Context, callerToken string) (*SAMLAnalyticsResponse, error)

SAMLAnalytics returns SAML usage analytics. GET /saml/analytics. Requires saml.read / system.admin.

func (*Client) SAMLAssertionConsumer 

func (c *Client) SAMLAssertionConsumer(ctx context.Context, form url.Values) (*SAMLAssertionResult, error)

SAMLAssertionConsumer processes a SAML response at the ACS (form-encoded), returning the resulting assertion/token payload. POST /saml/acs.

func (*Client) SAMLInitiateSLO added in v0.10.0 

func (c *Client) SAMLInitiateSLO(ctx context.Context, callerToken string) (string, error)

SAMLInitiateSLO initiates SAML Single Logout for the caller's session and returns the raw response (typically a redirect target or XML). POST /saml/slo/initiate.

func (*Client) SAMLMetadata 

func (c *Client) SAMLMetadata(ctx context.Context) (string, error)

SAMLMetadata fetches the IdP metadata XML. GET /saml/metadata.

func (*Client) SAMLSPMetadata 

func (c *Client) SAMLSPMetadata(ctx context.Context, spID string) (string, error)

SAMLSPMetadata fetches a service provider's metadata XML. GET /saml/sp/{sp_id}/metadata.

func (*Client) SAMLSSOPost 

func (c *Client) SAMLSSOPost(ctx context.Context, form url.Values) (string, error)

SAMLSSOPost performs a POST-binding SSO submission (form-encoded). POST /saml/sso.

func (*Client) SAMLSSORedirect 

func (c *Client) SAMLSSORedirect(ctx context.Context, params url.Values) (string, error)

SAMLSSORedirect performs an IdP-initiated/redirect-binding SSO GET, returning the raw response body (typically an HTML/redirect). GET /saml/sso.

func (*Client) SAMLServiceProviderMetadata added in v0.10.0 

func (c *Client) SAMLServiceProviderMetadata(ctx context.Context) (string, error)

SAMLServiceProviderMetadata returns this service's SAML SP metadata document (XML). GET /saml/sp/metadata.

func (*Client) SAMLSingleLogout 

func (c *Client) SAMLSingleLogout(ctx context.Context, form url.Values) (*SAMLLogoutResult, error)

SAMLSingleLogout processes a single-logout request/response. POST /saml/slo.

func (*Client) ScimResourceTypes added in v0.10.0 

func (c *Client) ScimResourceTypes(ctx context.Context, callerToken string) (*ScimListResponse, error)

ScimResourceTypes returns the SCIM resource types. GET /scim/v2/ResourceTypes.

func (*Client) ScimSchemas added in v0.10.0 

func (c *Client) ScimSchemas(ctx context.Context, callerToken string) (*ScimListResponse, error)

ScimSchemas returns the supported SCIM schemas. GET /scim/v2/Schemas.

func (*Client) ScimServiceProviderConfig added in v0.10.0 

func (c *Client) ScimServiceProviderConfig(ctx context.Context, callerToken string) (json.RawMessage, error)

ScimServiceProviderConfig returns the SCIM ServiceProviderConfig document. GET /scim/v2/ServiceProviderConfig. Shape is deployment-defined, so it is returned as raw JSON. 

func (c *Client) SendMagicLink(ctx context.Context, form url.Values) (*MagicLinkSendResponse, error)

SendMagicLink sends a login magic link (form-encoded). POST /auth/passwordless/magic-link/send.

func (*Client) SendTestEmail 

func (c *Client) SendTestEmail(ctx context.Context, orgID string, req TestEmailRequest, callerToken string) (*TestEmailSentResponse, error)

SendTestEmail sends a test email using an org's configuration. POST /organizations/{org_id}/emails/test. Requires org.admin.

func (*Client) SendVerificationEmail 

func (c *Client) SendVerificationEmail(ctx context.Context, req VerifyEmailSendRequest) error

SendVerificationEmail triggers an email-verification message. POST /auth/verify-email/send.

func (*Client) SetPasswordPolicy 

func (c *Client) SetPasswordPolicy(ctx context.Context, req PasswordPolicyRequest, callerToken string) (*PasswordPolicySetResponse, error)

SetPasswordPolicy sets a password policy. POST /admin/password-policy.

func (*Client) SetupOrgHierarchy 

func (c *Client) SetupOrgHierarchy(ctx context.Context, storeID string, req OrgHierarchyRequest, callerToken string) (*ZanzibarMessageResponse, error)

SetupOrgHierarchy configures org hierarchy tuples (requires zanzibar.admin). POST /zanzibar/stores/{store_id}/hierarchy/setup.

func (*Client) SetupTeamMembership 

func (c *Client) SetupTeamMembership(ctx context.Context, storeID string, req TeamMembershipRequest, callerToken string) (*ZanzibarMessageResponse, error)

SetupTeamMembership writes a team-membership tuple (requires zanzibar.admin). POST /zanzibar/stores/{store_id}/teams/membership.

func (*Client) SigningKey 

func (c *Client) SigningKey(ctx context.Context, kid string) (JWK, error)

SigningKey returns the cached signing key with the given kid, transparently refreshing the key set once if the kid is not found (handles key rotation).

func (*Client) Status 

func (c *Client) Status(ctx context.Context) (*ServiceStatusResponse, error)

Status returns service status. GET /status (public).

func (*Client) Store added in v0.3.0 

func (c *Client) Store(storeID, callerToken string) *ZanzibarStore

Store binds a store id and caller token so you stop repeating them. 

store := client.Store("my-store", userToken)
ok, err := store.Can(ctx, "user", "alice", "view", "doc", "123")

callerToken may be "" to use the client's configured service key.

func (*Client) SubmitReport 

func (c *Client) SubmitReport(ctx context.Context, req LeakReportSubmission) (*LeakReportSubmissionResponse, error)

SubmitReport submits an abuse/leak report. POST /reports (public).

func (*Client) SuperAdminActiveGrants 

func (c *Client) SuperAdminActiveGrants(ctx context.Context, callerToken string) (*SuperAdminActiveGrantsResponse, error)

SuperAdminActiveGrants lists active elevated grants (requires system.admin). GET /super-admin/active-grants.

func (*Client) SuperAdminApprove 

func (c *Client) SuperAdminApprove(ctx context.Context, req ApprovalRequestModel, callerToken string) (*MessageResponse, error)

SuperAdminApprove approves/denies a pending grant (must be a different admin than the requester). POST /super-admin/approve.

func (*Client) SuperAdminAuditLog 

func (c *Client) SuperAdminAuditLog(ctx context.Context, callerToken string) (*MessageResponse, error)

SuperAdminAuditLog returns the super-admin audit log (requires system.admin). GET /super-admin/audit-log.

func (*Client) SuperAdminCleanupExpired 

func (c *Client) SuperAdminCleanupExpired(ctx context.Context, callerToken string) (*SuperAdminCleanupResponse, error)

SuperAdminCleanupExpired purges expired grants (requires system.admin). POST /super-admin/cleanup-expired.

func (*Client) SuperAdminExtend 

func (c *Client) SuperAdminExtend(ctx context.Context, req SuperAdminExtendRequestModel, callerToken string) (*SuperAdminExtendResponse, error)

SuperAdminExtend extends an elevated grant's expiry (requires system.admin). POST /super-admin/extend.

func (*Client) SuperAdminGrant 

func (c *Client) SuperAdminGrant(ctx context.Context, req SuperAdminGrantRequestModel, callerToken string) (*SuperAdminGrantResponse, error)

SuperAdminGrant creates a time-bound elevated grant (requires system.admin). POST /super-admin/grant.

func (*Client) SuperAdminRevoke 

func (c *Client) SuperAdminRevoke(ctx context.Context, req SuperAdminRevokeRequestModel, callerToken string) (*SuperAdminRevokeResponse, error)

SuperAdminRevoke revokes an elevated grant (requires system.admin). POST /super-admin/revoke.

func (*Client) SupportedProviderTypes 

func (c *Client) SupportedProviderTypes(ctx context.Context) (map[string]any, error)

SupportedProviderTypes lists provider types the service supports. GET /providers/types/supported. PUBLIC.

func (*Client) SwitchOrganization 

func (c *Client) SwitchOrganization(ctx context.Context, token, orgID string) (*TokenSet, error)

SwitchOrganization re-issues tokens scoped to a different org/tenant. POST /auth/switch-organization. token must belong to a member of orgID.

func (*Client) SyncHRIS added in v0.10.0 

func (c *Client) SyncHRIS(ctx context.Context, orgID, callerToken string) (*HRISSyncResult, error)

SyncHRIS triggers a directory sync for an org's HRIS connection. POST /organizations/{org_id}/hris/sync. Requires org.admin.

func (*Client) TestEventSubscription 

func (c *Client) TestEventSubscription(ctx context.Context, subscriptionID, token string) (*EventSubscriptionTestResponse, error)

TestEventSubscription triggers a test delivery for a subscription. POST /events/subscriptions/{subscription_id}/test. Requires events.test.

func (*Client) TestProvider 

func (c *Client) TestProvider(ctx context.Context, req ProviderTestRequest, callerToken string) (*ProviderTestResponse, error)

TestProvider tests a provider's connectivity/config (requires org.admin). POST /providers/test.

func (*Client) ToggleEventSubscription 

func (c *Client) ToggleEventSubscription(ctx context.Context, subscriptionID, token string) (*EventSubscription, error)

ToggleEventSubscription enables/disables a subscription. POST /events/subscriptions/{subscription_id}/toggle. Requires events.update.

func (*Client) UpdateAPIKey 

func (c *Client) UpdateAPIKey(ctx context.Context, keyID string, req APIKeyUpdate, callerToken string) (*MessageResponse, error)

UpdateAPIKey updates an API key's metadata/permissions. PUT /api-keys/{key_id}.

func (*Client) UpdateClientRegistration 

func (c *Client) UpdateClientRegistration(ctx context.Context, clientID string, req ClientRegistration) (*ClientRegistrationResponse, error)

UpdateClientRegistration updates a dynamically-registered client. PUT /auth/oauth/register/{client_id}.

func (*Client) UpdateEventSubscription 

func (c *Client) UpdateEventSubscription(ctx context.Context, subscriptionID string, req EventSubscriptionUpdate, token string) (*EventSubscription, error)

UpdateEventSubscription partially updates a webhook subscription. PATCH /events/subscriptions/{subscription_id}. Requires events.update.

func (*Client) UpdateJITConfig 

func (c *Client) UpdateJITConfig(ctx context.Context, config map[string]any, callerToken string) (*MessageResponse, error)

UpdateJITConfig updates just-in-time provisioning config (requires org.admin). PUT /federation/jit/config.

func (*Client) UpdateLoginConfig 

func (c *Client) UpdateLoginConfig(ctx context.Context, orgID string, req LoginConfigUpdate, callerToken string) (*LoginConfigResponse, error)

UpdateLoginConfig updates a tenant's hosted-login configuration. PUT /organizations/{org_id}/login-config.

func (*Client) UpdateMyProfile 

func (c *Client) UpdateMyProfile(ctx context.Context, token string, upd UserUpdate) (*User, error)

UpdateMyProfile applies a partial update to the caller's profile. PUT /users/me.

func (*Client) UpdateNetworkPolicy 

func (c *Client) UpdateNetworkPolicy(ctx context.Context, policyID string, req UpdateNetworkPolicyRequest, callerToken string) (*NetworkPolicyStatusResponse, error)

UpdateNetworkPolicy updates a network policy. PUT /network-policy/{policy_id}.

func (*Client) UpdateOrgEmailConfig 

func (c *Client) UpdateOrgEmailConfig(ctx context.Context, orgID string, req OrgEmailConfigUpdate, callerToken string) (*OrgEmailConfigResponse, error)

UpdateOrgEmailConfig updates an org's email configuration. PUT /organizations/{org_id}/emails/config. Requires org.admin.

func (*Client) UpdateOrgEmailTemplate 

func (c *Client) UpdateOrgEmailTemplate(ctx context.Context, orgID, templateType string, req OrgEmailTemplateUpdate, callerToken string) (*OrgEmailTemplateResponse, error)

UpdateOrgEmailTemplate updates one of an org's email templates. PUT /organizations/{org_id}/emails/templates/{template_type}. Requires org.admin.

func (*Client) UpdateOrgUserRole 

func (c *Client) UpdateOrgUserRole(ctx context.Context, orgID, userID string, req OrgRoleUpdate, callerToken string) (*RoleUpdateResponse, error)

UpdateOrgUserRole changes a member's role/permissions (requires users.write). PUT /organizations/{org_id}/users/{user_id}.

func (*Client) UpdateOrganization 

func (c *Client) UpdateOrganization(ctx context.Context, orgID string, req OrganizationUpdate, callerToken string) (*MessageResponse, error)

UpdateOrganization updates an organization. PUT /organizations/{org_id}.

func (*Client) UpdatePasswordAge 

func (c *Client) UpdatePasswordAge(ctx context.Context, req PasswordAgeUpdate, callerToken string) (*PasswordAgeUpdateResponse, error)

UpdatePasswordAge sets a user's password age (test/admin helper). POST /admin/users/password-age.

func (*Client) UpdateProvider 

func (c *Client) UpdateProvider(ctx context.Context, providerID string, req ProviderConfigUpdate, callerToken string) (*MessageResponse, error)

UpdateProvider updates a provider config (requires org.admin). PUT /providers/{provider_id}.

func (*Client) UpdateProviderStatus 

func (c *Client) UpdateProviderStatus(ctx context.Context, req ProviderStatusUpdateRequest, callerToken string) (*ProviderStatusUpdateResponse, error)

UpdateProviderStatus enables/disables a provider (requires org.admin). POST /admin/providers/status.

func (*Client) UpdateSAMLAttributeMappings 

func (c *Client) UpdateSAMLAttributeMappings(ctx context.Context, req SAMLAttributeMappingUpdate, callerToken string) (*EnterpriseMessageResponse, error)

UpdateSAMLAttributeMappings updates the SAML attribute mappings. PUT /saml/attributes/mappings. Requires saml.admin / system.admin.

func (*Client) UpdateSAMLSP 

func (c *Client) UpdateSAMLSP(ctx context.Context, spID string, req SAMLServiceProviderConfig, callerToken string) (*SAMLSPUpdateResponse, error)

UpdateSAMLSP updates a service provider. PUT /saml/sp/{sp_id}. Requires saml.admin.

func (*Client) UpdateSSOConfig 

func (c *Client) UpdateSSOConfig(ctx context.Context, config map[string]any, callerToken string) (*SSOConfigUpdateResponse, error)

UpdateSSOConfig updates the org SSO configuration (requires org.admin). PUT /federation/sso/config.

func (*Client) UpdateSSODomain 

func (c *Client) UpdateSSODomain(ctx context.Context, domain string, req SSODomainConfigRequest, callerToken string) (*SSODomainConfigResponse, error)

UpdateSSODomain updates an SSO domain config (requires org.admin). PUT /federation/sso/domains/{domain}.

func (*Client) UpdateTeam 

func (c *Client) UpdateTeam(ctx context.Context, teamID string, req TeamUpdate, callerToken string) (*MessageResponse, error)

UpdateTeam updates a team (requires teams.write). PUT /teams/{team_id}.

func (*Client) UpdateTeamMemberRole 

func (c *Client) UpdateTeamMemberRole(ctx context.Context, teamID, userID string, req TeamMemberRoleUpdate, callerToken string) (*MessageResponse, error)

UpdateTeamMemberRole changes a team member's role (requires teams.write). PUT /teams/{team_id}/members/{user_id}.

func (*Client) UpdateUser 

func (c *Client) UpdateUser(ctx context.Context, userID string, upd UserUpdate, callerToken string) (*MessageResponse, error)

UpdateUser updates a user by id (requires users.write). PUT /users/{user_id}.

func (*Client) UpdateWebAuthnCredential 

func (c *Client) UpdateWebAuthnCredential(ctx context.Context, token, credentialID string, req WebAuthnCredentialUpdate) (*EnterpriseMessageResponse, error)

UpdateWebAuthnCredential renames one of the caller's credentials. PUT /auth/passwordless/webauthn/credentials/{credential_id}.

func (*Client) ValidateAPIKey 

func (c *Client) ValidateAPIKey(ctx context.Context, req ValidateAPIKeyRequest) (*APIKeyValidation, error)

ValidateAPIKey validates a service API key. POST /auth/validate-api-key.

func (*Client) ValidatePasswordResetToken 

func (c *Client) ValidatePasswordResetToken(ctx context.Context, token string) (*PasswordResetValidateResponse, error)

ValidatePasswordResetToken validates a reset token before showing the form. GET /auth/password-reset/validate.

func (*Client) ValidatePermissions 

func (c *Client) ValidatePermissions(ctx context.Context, perms []string) (*PermissionValidationResponse, error)

ValidatePermissions checks whether permission strings are registered/valid. POST /permissions/registry/validate. PUBLIC.

func (*Client) ValidateToken 

func (c *Client) ValidateToken(ctx context.Context, token string) (*Actor, error)

ValidateToken resolves a bearer credential to an Actor.

The credential may be a user JWT or a service/agent API key (ab0t_sk_…). The auth service resolves these at DIFFERENT endpoints — JWTs at POST /auth/validate-token, API keys at POST /auth/validate-api-key (the token endpoint does not resolve API keys). ValidateToken detects an API key by its prefix (IsAPIKey) and routes accordingly, adapting the API-key validation result into the same Actor shape, so a caller (and the resource server's Authenticate middleware) can treat both credential types uniformly.

The configured expected audience (WithExpectedAudience) is applied if set.

func (*Client) ValidateTokenWith 

func (c *Client) ValidateTokenWith(ctx context.Context, req TokenValidationRequest) (*Actor, error)

ValidateTokenWith performs a fully-specified validation, allowing inline permission and resource assertions. POST /auth/validate-token.

func (*Client) ValidationCacheStats added in v0.10.0 

func (c *Client) ValidationCacheStats() ValidationCacheStats

ValidationCacheStats returns a snapshot of cache activity. Safe to call concurrently; cheap enough to export as a metric. 

func (c *Client) VerifyMagicLink(ctx context.Context, form url.Values) (*PasswordlessAuthResponse, error)

VerifyMagicLink verifies a magic-link token and returns a token set (form-encoded). POST /auth/passwordless/magic-link/verify.

func (*Client) VerifyRecoveryCode 

func (c *Client) VerifyRecoveryCode(ctx context.Context, form url.Values) (*PasswordlessAuthResponse, error)

VerifyRecoveryCode authenticates using an MFA recovery code (form-encoded). POST /auth/passwordless/recovery-codes/verify.

func (*Client) VerifyUserEmail 

func (c *Client) VerifyUserEmail(ctx context.Context, userID, callerToken string) (*MessageResponse, error)

VerifyUserEmail force-marks a user's email verified (requires users.write). POST /users/{user_id}/verify-email.

func (*Client) VisualizeHierarchy 

func (c *Client) VisualizeHierarchy(ctx context.Context, storeID string, req VisualizationRequest, callerToken string) (*HierarchyVisualizationResponse, error)

VisualizeHierarchy renders an org/relationship hierarchy graph. POST /zanzibar/stores/{store_id}/visualize/hierarchy.

func (*Client) VisualizePermissions 

func (c *Client) VisualizePermissions(ctx context.Context, storeID, userID, callerToken string) (*PermissionsVisualizationResponse, error)

VisualizePermissions renders a user's permissions graph. The target user is passed as the `user_id` query parameter (required by the server). POST /zanzibar/stores/{store_id}/visualize/permissions.

func (*Client) WatchStatus 

func (c *Client) WatchStatus(ctx context.Context, storeID, callerToken string) (*WatchStatusResponse, error)

WatchStatus returns the change-stream/watch status for a store. GET /zanzibar/stores/{store_id}/watch/status.

func (*Client) WebAuthnAuthenticateFinish 

func (c *Client) WebAuthnAuthenticateFinish(ctx context.Context, assertion map[string]any) (*PasswordlessAuthResponse, error)

WebAuthnAuthenticateFinish completes a passkey authentication and returns a token set. POST /auth/passwordless/webauthn/authenticate/finish.

func (*Client) WebAuthnAuthenticateStart 

func (c *Client) WebAuthnAuthenticateStart(ctx context.Context, req map[string]any) (map[string]any, error)

WebAuthnAuthenticateStart begins a passkey authentication, returning the request options. POST /auth/passwordless/webauthn/authenticate/start.

func (*Client) WebAuthnConfig 

func (c *Client) WebAuthnConfig(ctx context.Context) (*WebAuthnConfigResponse, error)

WebAuthnConfig returns the relying-party WebAuthn configuration. GET /auth/passwordless/webauthn/config.

func (*Client) WebAuthnRegisterFinish 

func (c *Client) WebAuthnRegisterFinish(ctx context.Context, token string, credential map[string]any) (*WebAuthnRegistrationResult, error)

WebAuthnRegisterFinish completes a passkey registration with the authenticator's attestation. POST /auth/passwordless/webauthn/register/finish.

func (*Client) WebAuthnRegisterStart 

func (c *Client) WebAuthnRegisterStart(ctx context.Context, token string, req map[string]any) (map[string]any, error)

WebAuthnRegisterStart begins a passkey registration, returning the creation options the authenticator needs. POST /auth/passwordless/webauthn/register/start.

func (*Client) WriteAndDeleteRelationships 

func (c *Client) WriteAndDeleteRelationships(ctx context.Context, storeID string, req TransactRelationshipsRequest, token string) (*WriteOperationResponse, error)

WriteAndDeleteRelationships applies writes and deletes atomically and returns the resulting consistency token (WriteOperationResponse.ConsistencyToken) for read-after-write. Requires zanzibar.admin. POST /zanzibar/stores/{store_id}/relationships/transact.

SERVER-GAP: this endpoint does NOT exist in the auth service OpenAPI as of 2026-07-12 — the server exposes only separate POST and DELETE on /zanzibar/stores/{store_id}/relationships (no atomic combined transaction). Forward-looking; will 404 until the server implements it. Until then, use WriteRelationships + DeleteRelationships (non-atomic).

func (*Client) WriteAuthorizationModel 

func (c *Client) WriteAuthorizationModel(ctx context.Context, storeID string, req WriteAuthorizationModelRequest, callerToken string) (*WriteAuthorizationModelResponse, error)

WriteAuthorizationModel registers an authorization model (object types, relations, userset rewrites, wildcards) as a new immutable version and returns its id. Requires zanzibar.admin. POST /zanzibar/stores/{store_id}/authorization-models.

SERVER-GAP: this endpoint does NOT exist in the auth service OpenAPI as of 2026-07-12 — the service has no authorization-model management (it uses /zanzibar/stores/{store_id}/namespaces instead). Forward-looking; will 404 until the server implements it.

func (*Client) WriteRelationships 

func (c *Client) WriteRelationships(ctx context.Context, storeID string, req RelationshipRequest, token string) (*WriteOperationResponse, error)

WriteRelationships writes a single relationship tuple (requires zanzibar.admin). POST /zanzibar/stores/{store_id}/relationships.

func (*Client) ZanzibarCheck 

func (c *Client) ZanzibarCheck(ctx context.Context, storeID string, req CheckPermissionRequest, callerToken string) (*CheckPermissionResponse, error)

ZanzibarCheck performs a single permission check. POST /zanzibar/stores/{store_id}/check.

func (*Client) ZanzibarCheckBulk 

func (c *Client) ZanzibarCheckBulk(ctx context.Context, storeID string, req BulkCheckRequest, callerToken string) (BulkCheckResults, error)

ZanzibarCheckBulk performs multiple checks in one call. POST /zanzibar/stores/{store_id}/check/bulk. The results are returned IN REQUEST ORDER, one per element of req.Checks; index them with the same offset you built the request with, or use BulkCheckResults.Allowed(i).

func (*Client) ZanzibarCheckWildcard 

func (c *Client) ZanzibarCheckWildcard(ctx context.Context, storeID string, q url.Values, callerToken string) (*WildcardCheckResponse, error)

ZanzibarCheckWildcard evaluates a wildcard permission check. GET /zanzibar/stores/{store_id}/check/wildcard. The server reads the check parameters from the query string (e.g. user_id, permission).

func (*Client) ZanzibarExpand 

func (c *Client) ZanzibarExpand(ctx context.Context, storeID string, req ExpandRequest, callerToken string) (*ExpandResponse, error)

ZanzibarExpand expands a permission into its userset tree. POST /zanzibar/stores/{store_id}/expand.

func (*Client) ZanzibarGrant 

func (c *Client) ZanzibarGrant(ctx context.Context, storeID string, req PermissionGrantRequest, callerToken string) (*WriteOperationResponse, error)

ZanzibarGrant grants a permission via a relationship tuple (requires zanzibar.admin). POST /zanzibar/stores/{store_id}/permissions/grant.

func (*Client) ZanzibarListObjects 

func (c *Client) ZanzibarListObjects(ctx context.Context, storeID string, req ListObjectsRequest, callerToken string) (*ListObjectsResponse, error)

ZanzibarListObjects lists objects a subject can access via a permission. POST /zanzibar/stores/{store_id}/list-objects.

func (*Client) ZanzibarListUsers 

func (c *Client) ZanzibarListUsers(ctx context.Context, storeID string, req ListUsersRequest, callerToken string) (*ListUsersResponse, error)

ZanzibarListUsers lists subjects with a permission on an object. POST /zanzibar/stores/{store_id}/list-users.

func (*Client) ZanzibarRevoke 

func (c *Client) ZanzibarRevoke(ctx context.Context, storeID string, req PermissionGrantRequest, callerToken string) (*WriteOperationResponse, error)

ZanzibarRevoke revokes a permission relationship (requires zanzibar.admin). DELETE /zanzibar/stores/{store_id}/permissions/revoke.

type ClientRegistration 

type ClientRegistration struct {
	RedirectURIs            []string `json:"redirect_uris,omitempty"`
	ClientName              string   `json:"client_name,omitempty"`
	GrantTypes              []string `json:"grant_types,omitempty"`
	ResponseTypes           []string `json:"response_types,omitempty"`
	Scope                   string   `json:"scope,omitempty"`
	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
	Contacts                []string `json:"contacts,omitempty"`
	LogoURI                 string   `json:"logo_uri,omitempty"`
	PolicyURI               string   `json:"policy_uri,omitempty"`
}

ClientRegistration is the body for RFC 7591 dynamic client registration.

type ClientRegistrationResponse 

type ClientRegistrationResponse struct {
	ClientID                string   `json:"client_id"`
	ClientSecret            string   `json:"client_secret,omitempty"`
	ClientIDIssuedAt        int64    `json:"client_id_issued_at,omitempty"`
	ClientSecretExpiresAt   int64    `json:"client_secret_expires_at,omitempty"`
	RegistrationAccessToken string   `json:"registration_access_token,omitempty"`
	RegistrationClientURI   string   `json:"registration_client_uri,omitempty"`
	RedirectURIs            []string `json:"redirect_uris,omitempty"`
	ClientName              string   `json:"client_name,omitempty"`
	GrantTypes              []string `json:"grant_types,omitempty"`
	Scope                   string   `json:"scope,omitempty"`
	ClientURI               string   `json:"client_uri,omitempty"`
	Contacts                []string `json:"contacts,omitempty"`
	LogoURI                 string   `json:"logo_uri,omitempty"`
	OrgID                   string   `json:"org_id,omitempty"`
	PolicyURI               string   `json:"policy_uri,omitempty"`
	ResponseTypes           []string `json:"response_types,omitempty"`
	SoftwareID              string   `json:"software_id,omitempty"`
	SoftwareVersion         string   `json:"software_version,omitempty"`
	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
	TOSURI                  string   `json:"tos_uri,omitempty"`
}

ClientRegistrationResponse is the RFC 7591 registration result.

type CreateNetworkPolicyRequest 

type CreateNetworkPolicyRequest struct {
	OrgID                 string   `json:"org_id"`
	Name                  string   `json:"name"`
	Action                string   `json:"action"`
	Networks              []string `json:"networks"`
	Description           string   `json:"description,omitempty"`
	Priority              int      `json:"priority,omitempty"`
	GeoCountries          []string `json:"geo_countries,omitempty"`
	GeoMode               string   `json:"geo_mode,omitempty"`
	RestrictedPermissions []string `json:"restricted_permissions,omitempty"`
	RequireMFA            bool     `json:"require_mfa,omitempty"`
	ExpiresAt             string   `json:"expires_at,omitempty"`
}

CreateNetworkPolicyRequest is the body for POST /network-policy/. The server requires org_id, name, action and networks.

type DelegateTokenRequest 

type DelegateTokenRequest struct {
	TargetUserID string   `json:"target_user_id"`
	Permissions  []string `json:"permissions,omitempty"`
	OrgID        string   `json:"org_id,omitempty"`
}

DelegateTokenRequest is the body for POST /auth/delegate (mint an act-as token).

type DelegationCheckResponse 

type DelegationCheckResponse struct {
	CanDelegate bool     `json:"can_delegate"`
	Permissions []string `json:"permissions,omitempty"`
	Reason      string   `json:"reason,omitempty"`
	Allowed     bool     `json:"allowed,omitempty"`
	Scope       []string `json:"scope,omitempty"`
}

DelegationCheckResponse is the result of GET /delegation/check/{target_user_id}.

type DelegationEntry 

type DelegationEntry struct {
	ID           string   `json:"id"`
	ActorID      string   `json:"actor_id,omitempty"`
	TargetUserID string   `json:"target_user_id,omitempty"`
	Permissions  []string `json:"permissions,omitempty"`
	ExpiresAt    string   `json:"expires_at,omitempty"`
	CreatedAt    string   `json:"created_at,omitempty"`
}

DelegationEntry is one delegation grant from GET /delegation/list/{user_id}.

type DelegationGrant 

type DelegationGrant struct {
	ActorID string   `json:"actor_id"` // who may act (on the caller's behalf)
	Scope   []string `json:"scope"`    // the permission set the actor may use — REQUIRED
	// ExpiresInHours bounds the grant. REQUIRED by goauth; optional on Python.
	// Set it, or the goauth backend rejects the grant (422).
	ExpiresInHours *int `json:"expires_in_hours,omitempty"`
}

DelegationGrant is the body for POST /delegation/grant. DelegationGrant is the body for POST /delegation/grant. The target is the AUTHENTICATED caller (you grant an actor the right to act as YOU), so it is not in the body. (G-04) An earlier revision sent `permissions`/`target_user_id`/ `expires_at`/`reason` — none of which the server's request schema has; the server requires `scope` (the permission set) and, on goauth, `expires_in_hours`. So GrantDelegation could not succeed as-shipped (422). Fixed here.

type DelegationResponse 

type DelegationResponse struct {
	ID           string   `json:"id,omitempty"`
	ActorID      string   `json:"actor_id,omitempty"`
	TargetUserID string   `json:"target_user_id,omitempty"`
	Permissions  []string `json:"permissions,omitempty"`
	ExpiresAt    string   `json:"expires_at,omitempty"`
	Message      string   `json:"message,omitempty"`
	Success      bool     `json:"success,omitempty"`
}

DelegationResponse is the result of POST /delegation/grant.

type DeleteResult added in v0.10.0 

type DeleteResult struct {
	Deleted bool `json:"deleted"`
}

DeleteResult is a simple {deleted: bool} response.

type Device 

type Device struct {
	ID         string `json:"id"`
	Name       string `json:"name,omitempty"`
	Type       string `json:"type,omitempty"`
	LastSeenAt string `json:"last_seen_at,omitempty"`
	Trusted    bool   `json:"trusted,omitempty"`
}

Device is one entry returned by the device listing.

type DeviceListResponse 

type DeviceListResponse struct {
	Devices []Device `json:"devices"`
	Count   int64    `json:"count,omitempty"`
}

DeviceListResponse lists a user's known devices.

type DomainTokenResponse 

type DomainTokenResponse struct {
	Token     string `json:"token"`
	Domain    string `json:"domain,omitempty"`
	ExpiresIn int    `json:"expires_in,omitempty"`
	TokenType string `json:"token_type,omitempty"`
}

DomainTokenResponse is the result of POST /federation/sso/create-token.

type ElevatePrivilegesRequest 

type ElevatePrivilegesRequest struct {
	UserID          string   `json:"user_id"`
	Permissions     []string `json:"permissions"`
	DurationSeconds int      `json:"duration_seconds,omitempty"`
	Reason          string   `json:"reason,omitempty"`
}

ElevatePrivilegesRequest is the body for POST /admin/users/elevate-privileges.

type ElevatePrivilegesResponse 

type ElevatePrivilegesResponse struct {
	UserID                string   `json:"user_id,omitempty"`
	Granted               []string `json:"granted,omitempty"`
	ExpiresAt             string   `json:"expires_at,omitempty"`
	Message               string   `json:"message,omitempty"`
	ElevationExpiresAt    string   `json:"elevation_expires_at,omitempty"`
	NewRole               string   `json:"new_role,omitempty"`
	PasswordResetRequired bool     `json:"password_reset_required,omitempty"`
	StricterPolicyApplied bool     `json:"stricter_policy_applied,omitempty"`
}

ElevatePrivilegesResponse is the result of elevating a user's privileges.

type EmailConfigDeleteResponse 

type EmailConfigDeleteResponse struct {
	Message string `json:"message,omitempty"`
	Success bool   `json:"success,omitempty"`
}

EmailConfigDeleteResponse is the result of deleting an org email config.

type EmailHistoryEntry 

type EmailHistoryEntry struct {
	ID       string `json:"id,omitempty"`
	To       string `json:"to,omitempty"`
	Template string `json:"template,omitempty"`
	Status   string `json:"status,omitempty"`
	Subject  string `json:"subject,omitempty"`
	SentAt   string `json:"sent_at,omitempty"`
	Provider string `json:"provider,omitempty"`
	Error    string `json:"error,omitempty"`
}

EmailHistoryEntry is one sent-email record.

type EmailHistoryResponse 

type EmailHistoryResponse struct {
	Emails []EmailHistoryEntry `json:"emails"`
	Total  int                 `json:"total,omitempty"`
	Count  int64               `json:"count,omitempty"`
	Items  json.RawMessage     `json:"items,omitempty"`
	OrgID  string              `json:"org_id,omitempty"`
}

EmailHistoryResponse lists sent emails.

type EmailStatsResponse 

type EmailStatsResponse struct {
	Sent      int              `json:"sent,omitempty"`
	Delivered int              `json:"delivered,omitempty"`
	Failed    int              `json:"failed,omitempty"`
	Bounced   int              `json:"bounced,omitempty"`
	Stats     map[string]any   `json:"stats,omitempty"`
	ByStatus  map[string]int64 `json:"by_status,omitempty"`
	ByType    map[string]int64 `json:"by_type,omitempty"`
	OrgID     string           `json:"org_id,omitempty"`
	Total     int64            `json:"total,omitempty"`
}

EmailStatsResponse reports aggregate email statistics.

type EmailTemplateDeleteResponse 

type EmailTemplateDeleteResponse struct {
	Message string `json:"message,omitempty"`
	Success bool   `json:"success,omitempty"`
}

EmailTemplateDeleteResponse is the result of deleting an org email template.

type EmergencyOverrideCreateResponse 

type EmergencyOverrideCreateResponse struct {
	OverrideID string `json:"override_id"`
	ExpiresAt  string `json:"expires_at,omitempty"`
	Message    string `json:"message,omitempty"`
	Status     string `json:"status,omitempty"`
	UserID     string `json:"user_id,omitempty"`
}

EmergencyOverrideCreateResponse is the result of creating an override.

type EmergencyOverrideRequest 

type EmergencyOverrideRequest struct {
	IP         string `json:"ip"`
	Reason     string `json:"reason,omitempty"`
	TTLSeconds int    `json:"ttl_seconds,omitempty"`
}

EmergencyOverrideRequest is the body for POST /network-policy/emergency-override.

type EmergencyRevokeRequest 

type EmergencyRevokeRequest struct {
	KeyIDs  []string `json:"key_ids,omitempty"`
	OrgID   string   `json:"org_id,omitempty"`
	AllKeys bool     `json:"all_keys,omitempty"`
	Reason  string   `json:"reason,omitempty"`
}

EmergencyRevokeRequest is the body for POST /admin/api-keys/emergency-revoke.

type EmergencyRevokeResponse 

type EmergencyRevokeResponse struct {
	RevokedCount int    `json:"revoked_count,omitempty"`
	Message      string `json:"message,omitempty"`
	IncidentID   string `json:"incident_id,omitempty"`
	KeyID        string `json:"key_id,omitempty"`
	Reason       string `json:"reason,omitempty"`
	RevokedAt    string `json:"revoked_at,omitempty"`
	RevokedBy    string `json:"revoked_by,omitempty"`
	Severity     string `json:"severity,omitempty"`
}

EmergencyRevokeResponse is the result of emergency API-key revocation.

type EnterpriseMessageResponse 

type EnterpriseMessageResponse struct {
	Message string `json:"message,omitempty"`
	Success bool   `json:"success,omitempty"`
	Detail  string `json:"detail,omitempty"`
}

EnterpriseMessageResponse is the {message,...} envelope returned by the enterprise (passwordless/SAML/federation) endpoints.

type ErrUntypedID added in v0.2.0 

type ErrUntypedID struct {
	Field string // which request field ("subject", "object", …)
	Value string
}

ErrUntypedID reports an id that is missing its "type:" prefix. Build ids with Object() / Subject() rather than concatenating strings.

func (*ErrUntypedID) Error added in v0.2.0 

func (e *ErrUntypedID) Error() string

type EventFilter added in v0.10.0 

type EventFilter struct {
	Field    string `json:"field"`
	Operator string `json:"operator"`
	Value    any    `json:"value"`
}

EventFilter narrows which events a subscription receives.

type EventSubscription 

type EventSubscription struct {
	SubscriptionID     string            `json:"subscription_id,omitempty"`
	TenantID           string            `json:"tenant_id,omitempty"`
	Name               string            `json:"name,omitempty"`
	Description        string            `json:"description,omitempty"`
	EventTypes         []string          `json:"event_types,omitempty"`
	Filters            []EventFilter     `json:"filters,omitempty"`
	DeliveryMethod     string            `json:"delivery_method,omitempty"`
	Endpoint           string            `json:"endpoint,omitempty"`
	Secret             string            `json:"secret,omitempty"`
	Headers            map[string]string `json:"headers,omitempty"`
	IsActive           bool              `json:"is_active,omitempty"`
	RetryPolicy        *RetryPolicy      `json:"retry_policy,omitempty"`
	BatchSize          int               `json:"batch_size,omitempty"`
	BatchTimeoutMs     int               `json:"batch_timeout_ms,omitempty"`
	MaxEventsPerMinute int               `json:"max_events_per_minute,omitempty"`
	CreatedAt          string            `json:"created_at,omitempty"`
	UpdatedAt          string            `json:"updated_at,omitempty"`
	CreatedBy          string            `json:"created_by,omitempty"`
	LastDeliveryAt     string            `json:"last_delivery_at,omitempty"`
	LastDeliveryStatus string            `json:"last_delivery_status,omitempty"`
	TotalDeliveries    int               `json:"total_deliveries,omitempty"`
	FailedDeliveries   int               `json:"failed_deliveries,omitempty"`
}

EventSubscription is a webhook subscription (EventSubscription in the API).

type EventSubscriptionCreate 

type EventSubscriptionCreate struct {
	Name               string            `json:"name"`
	EventTypes         []string          `json:"event_types"`
	Endpoint           string            `json:"endpoint"`
	Description        string            `json:"description,omitempty"`
	Filters            []EventFilter     `json:"filters,omitempty"`
	DeliveryMethod     string            `json:"delivery_method,omitempty"`
	Secret             string            `json:"secret,omitempty"`
	Headers            map[string]string `json:"headers,omitempty"`
	RetryPolicy        *RetryPolicy      `json:"retry_policy,omitempty"`
	BatchSize          int               `json:"batch_size,omitempty"`
	BatchTimeoutMs     int               `json:"batch_timeout_ms,omitempty"`
	MaxEventsPerMinute int               `json:"max_events_per_minute,omitempty"`
}

EventSubscriptionCreate is the body for POST /events/subscriptions. The server requires name, event_types and endpoint.

type EventSubscriptionListResponse 

type EventSubscriptionListResponse struct {
	Items        []EventSubscription `json:"items"`
	Count        int                 `json:"count,omitempty"`
	NextToken    string              `json:"next_token,omitempty"`
	TotalScanned int64               `json:"total_scanned,omitempty"`
}

EventSubscriptionListResponse lists webhook subscriptions.

type EventSubscriptionStatsResponse 

type EventSubscriptionStatsResponse struct {
	Delivered int            `json:"delivered,omitempty"`
	Failed    int            `json:"failed,omitempty"`
	Pending   int            `json:"pending,omitempty"`
	Stats     map[string]any `json:"stats,omitempty"`
}

EventSubscriptionStatsResponse reports delivery statistics.

type EventSubscriptionTestResponse 

type EventSubscriptionTestResponse struct {
	Success      bool   `json:"success,omitempty"`
	StatusCode   int    `json:"status_code,omitempty"`
	ResponseBody string `json:"response_body,omitempty"`
	Message      string `json:"message,omitempty"`
}

EventSubscriptionTestResponse is the result of a test delivery.

type EventSubscriptionUpdate 

type EventSubscriptionUpdate struct {
	Name               *string            `json:"name,omitempty"`
	EventTypes         *[]string          `json:"event_types,omitempty"`
	Endpoint           *string            `json:"endpoint,omitempty"`
	Description        *string            `json:"description,omitempty"`
	Filters            *[]EventFilter     `json:"filters,omitempty"`
	DeliveryMethod     *string            `json:"delivery_method,omitempty"`
	Secret             *string            `json:"secret,omitempty"`
	Headers            *map[string]string `json:"headers,omitempty"`
	RetryPolicy        *RetryPolicy       `json:"retry_policy,omitempty"`
	BatchSize          *int               `json:"batch_size,omitempty"`
	BatchTimeoutMs     *int               `json:"batch_timeout_ms,omitempty"`
	MaxEventsPerMinute *int               `json:"max_events_per_minute,omitempty"`
	IsActive           *bool              `json:"is_active,omitempty"`
}

EventSubscriptionUpdate is the body for PATCH /events/subscriptions/{id}.

type EventTypeInfo 

type EventTypeInfo struct {
	Type        string `json:"type"`
	Description string `json:"description,omitempty"`
	Category    string `json:"category,omitempty"`
}

EventTypeInfo describes one emittable event type.

type EventTypesResponse 

type EventTypesResponse struct {
	EventTypes     []EventTypeInfo `json:"event_types"`
	APIKeys        json.RawMessage `json:"api_keys,omitempty"`
	Authentication json.RawMessage `json:"authentication,omitempty"`
	Organization   json.RawMessage `json:"organization,omitempty"`
	Permissions    json.RawMessage `json:"permissions,omitempty"`
	Providers      json.RawMessage `json:"providers,omitempty"`
	Security       json.RawMessage `json:"security,omitempty"`
}

EventTypesResponse lists available event types.

type ExpandRequest 

type ExpandRequest struct {
	Permission string `json:"permission"`
	Object     string `json:"object"`
	OrgID      string `json:"org_id,omitempty"`
	MaxDepth   int    `json:"max_depth,omitempty"`
}

ExpandRequest is the body for POST /zanzibar/stores/{store_id}/expand. Matches OpenAPI schema ExpandRequest (required: permission, object).

type ExpandResponse 

type ExpandResponse struct {
	Object      string         `json:"object"`
	Permission  string         `json:"permission"`
	Subjects    []string       `json:"subjects,omitempty"`
	UsersetTree map[string]any `json:"userset_tree,omitempty"`
}

ExpandResponse is the result of expanding a permission into its userset tree. Matches OpenAPI schema ExpandResponse (required: object, permission).

type FederationStatsResponse 

type FederationStatsResponse struct {
	ActiveSessions int             `json:"active_sessions,omitempty"`
	Domains        int             `json:"domains,omitempty"`
	Providers      int             `json:"providers,omitempty"`
	Stats          map[string]any  `json:"stats,omitempty"`
	SAML           json.RawMessage `json:"saml,omitempty"`
	SSO            json.RawMessage `json:"sso,omitempty"`
	Webauthn       json.RawMessage `json:"webauthn,omitempty"`
}

FederationStatsResponse is the result of GET /federation/stats.

type ForcePasswordResetRequest 

type ForcePasswordResetRequest struct {
	OrgID    string   `json:"org_id,omitempty"`
	UserIDs  []string `json:"user_ids,omitempty"`
	AllUsers bool     `json:"all_users,omitempty"`
}

ForcePasswordResetRequest is the body for POST /admin/password-policy/force-reset.

type ForcePasswordResetResponse 

type ForcePasswordResetResponse struct {
	Message          string `json:"message,omitempty"`
	AffectedCount    int    `json:"affected_count,omitempty"`
	AffectedUsers    int64  `json:"affected_users,omitempty"`
	GracePeriodHours int64  `json:"grace_period_hours,omitempty"`
}

ForcePasswordResetResponse is the result of forcing password resets.

type ForwardAuthDecision 

type ForwardAuthDecision struct {
	// Allowed is true when the forward-auth endpoint returned a 2xx.
	Allowed bool
	// StatusCode is the HTTP status the auth service returned.
	StatusCode int
	// Body is the raw response body (may carry identity headers/JSON).
	Body string
}

ForwardAuthDecision reports a proxy auth decision plus echoed headers.

type GlobalEmailConfigResponse 

type GlobalEmailConfigResponse struct {
	Provider    string         `json:"provider,omitempty"`
	FromAddress string         `json:"from_address,omitempty"`
	FromName    string         `json:"from_name,omitempty"`
	Configured  bool           `json:"configured,omitempty"`
	Settings    map[string]any `json:"settings,omitempty"`
	SafeMode    bool           `json:"safe_mode,omitempty"`
	TestMode    bool           `json:"test_mode,omitempty"`
}

GlobalEmailConfigResponse is the system-wide email configuration.

type HRISConfigureRequest added in v0.10.0 

type HRISConfigureRequest struct {
	Provider string `json:"provider"`
	BaseURL  string `json:"base_url"`
	APIKey   string `json:"api_key"`
}

HRISConfigureRequest configures an org's HRIS connection.

type HRISConnectionStatus added in v0.10.0 

type HRISConnectionStatus struct {
	Provider   string `json:"provider"`
	Configured bool   `json:"configured"`
	Active     bool   `json:"active"`
	BaseURL    string `json:"base_url"`
	CreatedAt  string `json:"created_at,omitempty"`
	LastSyncAt string `json:"last_sync_at,omitempty"`
}

HRISConnectionStatus is the state of an org's HRIS directory connection.

type HRISSyncResult added in v0.10.0 

type HRISSyncResult struct {
	Provider      string   `json:"provider"`
	RosterSize    int64    `json:"roster_size"`
	Provisioned   int64    `json:"provisioned"`
	Deprovisioned int64    `json:"deprovisioned"`
	Unchanged     int64    `json:"unchanged"`
	Errors        []string `json:"errors,omitempty"`
}

HRISSyncResult reports the outcome of a directory sync.

type HealthCheckResponse 

type HealthCheckResponse struct {
	Status  string `json:"status"`
	Version string `json:"version,omitempty"`
	// Timestamp is a Unix epoch (seconds, fractional). The service returns it as
	// a JSON NUMBER — modeling it as a string made encoding/json fail the whole
	// /health decode.
	Timestamp         float64         `json:"timestamp,omitempty"`
	Dependencies      json.RawMessage `json:"dependencies,omitempty"`
	CircuitBreakers   json.RawMessage `json:"circuit_breakers,omitempty"`
	Metrics           json.RawMessage `json:"metrics,omitempty"`
	Enterprise        json.RawMessage `json:"enterprise,omitempty"`
	OAuth21           json.RawMessage `json:"oauth21,omitempty"`
	ZanzibarMigration json.RawMessage `json:"zanzibar_migration,omitempty"`
	// Additional operational fields some auth-service versions include.
	Checks         json.RawMessage `json:"checks,omitempty"`
	Runtime        json.RawMessage `json:"runtime,omitempty"`
	Service        string          `json:"service,omitempty"`
	UptimeSec      float64         `json:"uptime_sec,omitempty"`
	PasswordPolicy json.RawMessage `json:"password_policy,omitempty"`
}

HealthCheckResponse is the result of GET /health. Fields are the union across auth backends; nested objects are left as raw JSON so callers can decode the parts they need without this type tracking every backend's internal shape.

type HierarchyTeam added in v0.9.0 

type HierarchyTeam struct {
	ID      string          `json:"id,omitempty"`
	Type    string          `json:"type,omitempty"`
	Members []HierarchyUser `json:"members,omitempty"`
}

HierarchyTeam is one team inside an organization in a hierarchy response.

type HierarchyUser added in v0.9.0 

type HierarchyUser struct {
	ID   string `json:"id,omitempty"`
	Type string `json:"type,omitempty"`
	Role string `json:"role,omitempty"`
}

HierarchyUser is one user inside a team in a hierarchy response.

type HierarchyVisualizationResponse 

type HierarchyVisualizationResponse struct {
	ID          string           `json:"id"`
	Type        string           `json:"type,omitempty"`
	Children    []any            `json:"children,omitempty"`
	Users       []map[string]any `json:"users,omitempty"`
	Teams       []map[string]any `json:"teams,omitempty"`
	Permissions []any            `json:"permissions,omitempty"`
}

HierarchyVisualizationResponse is a hierarchy tree node. Matches OpenAPI schema HierarchyVisualizationResponse (required: id). Children and Permissions are left generic because the OpenAPI leaves their item schema untyped; Users/Teams are objects.

type HostedLoginMessageResponse 

type HostedLoginMessageResponse struct {
	Message string `json:"message,omitempty"`
	Success bool   `json:"success,omitempty"`
}

HostedLoginMessageResponse is the message envelope returned by hosted-login auth endpoints (org-scoped logout / reset-password).

type Introspection 

type Introspection struct {
	Active    bool   `json:"active"`
	Scope     string `json:"scope,omitempty"`
	ClientID  string `json:"client_id,omitempty"`
	Username  string `json:"username,omitempty"`
	TokenType string `json:"token_type,omitempty"`
	Subject   string `json:"sub,omitempty"`
	OrgID     string `json:"org_id,omitempty"`
	Issuer    string `json:"iss,omitempty"`
	JTI       string `json:"jti,omitempty"`
	Audience  any    `json:"aud,omitempty"` // string or []string per RFC 7662
	Exp       int64  `json:"exp,omitempty"`
	Iat       int64  `json:"iat,omitempty"`
}

Introspection is the RFC 7662 response from POST /token/introspect.

type InvitationListItem 

type InvitationListItem struct {
	ID          string   `json:"id"`
	Email       string   `json:"email"`
	Role        string   `json:"role,omitempty"`
	Status      string   `json:"status,omitempty"`
	InvitedBy   string   `json:"invited_by,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
	TeamID      string   `json:"team_id,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	ExpiresAt   string   `json:"expires_at,omitempty"`
	UsedAt      string   `json:"used_at,omitempty"`
	CancelledAt string   `json:"cancelled_at,omitempty"`
}

InvitationListItem is one entry from GET /organizations/{org_id}/invitations.

type JITConfigResponse 

type JITConfigResponse struct {
	Enabled        bool           `json:"enabled,omitempty"`
	DefaultRole    string         `json:"default_role,omitempty"`
	AllowedDomains []string       `json:"allowed_domains,omitempty"`
	Config         map[string]any `json:"config,omitempty"`
	AutoActivate   bool           `json:"auto_activate,omitempty"`
	SyncAttributes bool           `json:"sync_attributes,omitempty"`
}

JITConfigResponse is the result of GET /federation/jit/config (just-in-time provisioning).

type JWK 

type JWK struct {
	Kty string `json:"kty"`           // key type: "RSA", "EC", "oct"
	Use string `json:"use,omitempty"` // "sig" or "enc"
	Kid string `json:"kid,omitempty"` // key id
	Alg string `json:"alg,omitempty"` // e.g. "RS256", "ES256"

	// RSA.
	N string `json:"n,omitempty"`
	E string `json:"e,omitempty"`

	// EC.
	Crv string `json:"crv,omitempty"`
	X   string `json:"x,omitempty"`
	Y   string `json:"y,omitempty"`

	// X.509 chain (optional).
	X5c []string `json:"x5c,omitempty"`
	X5t string   `json:"x5t,omitempty"`
}

JWK is a single JSON Web Key (RFC 7517). Only the commonly-needed fields are modeled; unknown fields are ignored. For RSA keys N and E are base64url; for EC keys Crv, X, and Y are populated.

type JWKS 

type JWKS struct {
	Keys []JWK `json:"keys"`
}

JWKS is a JSON Web Key Set (GET /.well-known/jwks.json).

func (JWKS) Key 

func (s JWKS) Key(kid string) (JWK, bool)

Key returns the key with the matching kid, or false if absent.

type JwksHealthResponse 

type JwksHealthResponse struct {
	Healthy          bool   `json:"healthy"`
	ActiveKeys       int    `json:"active_keys,omitempty"`
	Message          string `json:"message,omitempty"`
	ActiveKeyCreated string `json:"active_key_created,omitempty"`
	ActiveKeyID      string `json:"active_key_id,omitempty"`
	Algorithm        string `json:"algorithm,omitempty"`
	Error            string `json:"error,omitempty"`
	Status           string `json:"status,omitempty"`
	TotalKeys        int64  `json:"total_keys,omitempty"`
}

JwksHealthResponse is the result of GET /health/jwks.

type JwksMetricsResponse 

type JwksMetricsResponse struct {
	ActiveKeys      int             `json:"active_keys,omitempty"`
	RevokedKeys     int             `json:"revoked_keys,omitempty"`
	LastRotation    string          `json:"last_rotation,omitempty"`
	NextRotation    string          `json:"next_rotation,omitempty"`
	Metrics         map[string]any  `json:"metrics,omitempty"`
	Configuration   json.RawMessage `json:"configuration,omitempty"`
	KeyMetrics      json.RawMessage `json:"key_metrics,omitempty"`
	RotationHealth  json.RawMessage `json:"rotation_health,omitempty"`
	RotationMetrics json.RawMessage `json:"rotation_metrics,omitempty"`
}

JwksMetricsResponse reports JWKS operational metrics.

type JwksRecoverResponse 

type JwksRecoverResponse struct {
	Recovered   bool   `json:"recovered,omitempty"`
	Message     string `json:"message,omitempty"`
	ActiveKeyID string `json:"active_key_id,omitempty"`
	Status      string `json:"status,omitempty"`
	TotalKeys   int64  `json:"total_keys,omitempty"`
}

JwksRecoverResponse is the result of POST /health/jwks/recover.

type KeyActivateResponse 

type KeyActivateResponse struct {
	Kid         string `json:"kid,omitempty"`
	Active      bool   `json:"active,omitempty"`
	Message     string `json:"message,omitempty"`
	ActivatedAt string `json:"activated_at,omitempty"`
	Success     bool   `json:"success,omitempty"`
}

KeyActivateResponse is the result of POST /admin/jwks/activate/{kid}.

type KeyCleanupRequest 

type KeyCleanupRequest struct {
	OlderThanDays int  `json:"older_than_days,omitempty"`
	DryRun        bool `json:"dry_run,omitempty"`
}

KeyCleanupRequest is the body for POST /admin/jwks/cleanup.

type KeyCleanupResponse 

type KeyCleanupResponse struct {
	RemovedCount    int             `json:"removed_count,omitempty"`
	RemovedKids     []string        `json:"removed_kids,omitempty"`
	Message         string          `json:"message,omitempty"`
	DryRun          bool            `json:"dry_run,omitempty"`
	Force           bool            `json:"force,omitempty"`
	KeysCleaned     int64           `json:"keys_cleaned,omitempty"`
	KeysIdentified  json.RawMessage `json:"keys_identified,omitempty"`
	Timestamp       string          `json:"timestamp,omitempty"`
	TotalKeysBefore int64           `json:"total_keys_before,omitempty"`
}

KeyCleanupResponse is the result of cleaning up old keys.

type KeyGenerateResponse 

type KeyGenerateResponse struct {
	Kid       string `json:"kid,omitempty"`
	Message   string `json:"message,omitempty"`
	CreatedAt string `json:"created_at,omitempty"`
	ExpiresAt string `json:"expires_at,omitempty"`
	Status    string `json:"status,omitempty"`
	Success   bool   `json:"success,omitempty"`
}

KeyGenerateResponse is the result of generating a key.

type KeyGenerationRequest 

type KeyGenerationRequest struct {
	Algorithm string `json:"algorithm,omitempty"`
	Activate  bool   `json:"activate,omitempty"`
}

KeyGenerationRequest is the body for POST /admin/jwks/generate.

type KeyRevocationRequest 

type KeyRevocationRequest struct {
	Reason string `json:"reason,omitempty"`
}

KeyRevocationRequest is the body for POST /admin/jwks/revoke/{kid}.

type KeyRevocationResponse 

type KeyRevocationResponse struct {
	Kid               string          `json:"kid,omitempty"`
	Revoked           bool            `json:"revoked,omitempty"`
	Message           string          `json:"message,omitempty"`
	NotificationsSent int64           `json:"notifications_sent,omitempty"`
	ReplacementKey    json.RawMessage `json:"replacement_key,omitempty"`
	RevokedAt         string          `json:"revoked_at,omitempty"`
	Success           bool            `json:"success,omitempty"`
}

KeyRevocationResponse is the result of revoking a signing key.

type KeyRotationRequest 

type KeyRotationRequest struct {
	Algorithm string `json:"algorithm,omitempty"`
	Force     bool   `json:"force,omitempty"`
}

KeyRotationRequest is the body for POST /admin/jwks/rotate.

type KeyRotationResponse 

type KeyRotationResponse struct {
	NewKid              string          `json:"new_kid,omitempty"`
	Message             string          `json:"message,omitempty"`
	Error               string          `json:"error,omitempty"`
	NewKey              json.RawMessage `json:"new_key,omitempty"`
	NextRotationDate    string          `json:"next_rotation_date,omitempty"`
	Reason              string          `json:"reason,omitempty"`
	RotationCompletedAt string          `json:"rotation_completed_at,omitempty"`
	Success             bool            `json:"success,omitempty"`
}

KeyRotationResponse is the result of rotating signing keys.

type LeakReport 

type LeakReport struct {
	ID          string `json:"id"`
	Type        string `json:"type,omitempty"`
	Description string `json:"description,omitempty"`
	Status      string `json:"status,omitempty"`
	CreatedAt   string `json:"created_at,omitempty"`
}

LeakReport is one abuse report entry.

type LeakReportActionResponse 

type LeakReportActionResponse struct {
	ReportID string `json:"report_id,omitempty"`
	Status   string `json:"status,omitempty"`
	Message  string `json:"message,omitempty"`
}

LeakReportActionResponse is the result of dismiss/resolve.

type LeakReportListResponse 

type LeakReportListResponse struct {
	Reports []LeakReport `json:"reports"`
	Total   int          `json:"total,omitempty"`
}

LeakReportListResponse lists abuse reports.

type LeakReportSubmission 

type LeakReportSubmission struct {
	Type          string         `json:"type,omitempty"`
	Description   string         `json:"description,omitempty"`
	URL           string         `json:"url,omitempty"`
	Evidence      string         `json:"evidence,omitempty"`
	ReporterEmail string         `json:"reporter_email,omitempty"`
	Metadata      map[string]any `json:"metadata,omitempty"`
}

LeakReportSubmission is the body for POST /reports.

type LeakReportSubmissionResponse 

type LeakReportSubmissionResponse struct {
	ReportID string `json:"report_id"`
	Message  string `json:"message,omitempty"`
	Status   string `json:"status,omitempty"`
}

LeakReportSubmissionResponse is the result of submitting an abuse report.

type ListAuthorizationModelsResponse 

type ListAuthorizationModelsResponse struct {
	Models            []AuthorizationModelResponse `json:"models"`
	ContinuationToken string                       `json:"continuation_token,omitempty"`
}

ListAuthorizationModelsResponse lists model versions, newest first.

type ListObjectsRequest 

type ListObjectsRequest struct {
	Subject          string `json:"subject"`
	Permission       string `json:"permission"`
	ObjectType       string `json:"object_type"`
	OrgID            string `json:"org_id,omitempty"`
	MaxResults       int    `json:"max_results,omitempty"`
	ConsistencyToken string `json:"consistency_token,omitempty"`
}

ListObjectsRequest is the body for POST /zanzibar/stores/{store_id}/list-objects. Matches OpenAPI schema ListObjectsRequest (required: subject, permission, object_type). MaxResults caps the result set (1..1000, server default 1000).

type ListObjectsResponse 

type ListObjectsResponse struct {
	Objects     []string `json:"objects,omitempty"`
	Subject     string   `json:"subject"`
	Permission  string   `json:"permission"`
	ObjectType  string   `json:"object_type"`
	ResultCount int      `json:"result_count,omitempty"`
	// ContinuationToken is reserved for future use by the server (currently always
	// empty); it is NOT accepted on the request side.
	ContinuationToken string `json:"continuation_token,omitempty"`
}

ListObjectsResponse lists the object ids a subject can access. Matches OpenAPI schema ListObjectsResponse (required: subject, permission, object_type).

type ListUsersRequest 

type ListUsersRequest struct {
	Object           string `json:"object"`
	Permission       string `json:"permission"`
	OrgID            string `json:"org_id,omitempty"`
	MaxResults       int    `json:"max_results,omitempty"`
	ExpandGroups     *bool  `json:"expand_groups,omitempty"`
	ConsistencyToken string `json:"consistency_token,omitempty"`
}

ListUsersRequest is the body for POST /zanzibar/stores/{store_id}/list-users. Matches OpenAPI schema ListUsersRequest (required: object, permission). ExpandGroups defaults to true server-side; leave nil to accept that default.

type ListUsersResponse 

type ListUsersResponse struct {
	Users       []string `json:"users,omitempty"`
	Object      string   `json:"object"`
	Permission  string   `json:"permission"`
	ResultCount int      `json:"result_count,omitempty"`
	// ContinuationToken is reserved for future use (currently always empty).
	ContinuationToken string `json:"continuation_token,omitempty"`
}

ListUsersResponse lists the subject ids that can access an object. Matches OpenAPI schema ListUsersResponse (required: object, permission).

type LoginConfig 

type LoginConfig struct {
	OrgID             string         `json:"org_id,omitempty"`
	LogoURL           string         `json:"logo_url,omitempty"`
	PrimaryColor      string         `json:"primary_color,omitempty"`
	BackgroundColor   string         `json:"background_color,omitempty"`
	AllowPassword     bool           `json:"allow_password,omitempty"`
	AllowSignup       bool           `json:"allow_signup,omitempty"`
	AllowPasswordless bool           `json:"allow_passwordless,omitempty"`
	TermsURL          string         `json:"terms_url,omitempty"`
	PrivacyURL        string         `json:"privacy_url,omitempty"`
	CustomCSS         string         `json:"custom_css,omitempty"`
	Settings          map[string]any `json:"settings,omitempty"`
}

LoginConfig describes a tenant's hosted-login branding and behaviour.

type LoginConfigResponse 

type LoginConfigResponse struct {
	Config LoginConfig `json:"config"`
}

LoginConfigResponse wraps the tenant login configuration.

type LoginConfigUpdate 

type LoginConfigUpdate struct {
	LogoURL           *string         `json:"logo_url,omitempty"`
	PrimaryColor      *string         `json:"primary_color,omitempty"`
	BackgroundColor   *string         `json:"background_color,omitempty"`
	AllowPassword     *bool           `json:"allow_password,omitempty"`
	AllowSignup       *bool           `json:"allow_signup,omitempty"`
	AllowPasswordless *bool           `json:"allow_passwordless,omitempty"`
	TermsURL          *string         `json:"terms_url,omitempty"`
	PrivacyURL        *string         `json:"privacy_url,omitempty"`
	CustomCSS         *string         `json:"custom_css,omitempty"`
	Settings          *map[string]any `json:"settings,omitempty"`
}

LoginConfigUpdate is the body for PUT /organizations/{org_id}/login-config.

type LoginRequest 

type LoginRequest struct {
	Email    string `json:"email"`
	Password string `json:"password"`
	// OrgID selects a specific organization for a multi-org user. Optional.
	OrgID string `json:"org_id,omitempty"`
	// ProviderType selects an auth provider (e.g. "internal", "google").
	// Defaults server-side to "internal".
	ProviderType string `json:"provider_type,omitempty"`
}

LoginRequest is the body for POST /auth/login.

type LogoutPropagationResponse 

type LogoutPropagationResponse struct {
	Success     bool     `json:"success,omitempty"`
	LoggedOutOf []string `json:"logged_out_of,omitempty"`
	Message     string   `json:"message,omitempty"`
	SessionID   string   `json:"session_id,omitempty"`
	Status      string   `json:"status,omitempty"`
}

LogoutPropagationResponse is the result of POST /federation/sso/propagate-logout.

type LogoutResult 

type LogoutResult struct {
	Success bool   `json:"success,omitempty"`
	Message string `json:"message,omitempty"`
}

LogoutResult is the response from POST /auth/logout.

type MagicLinkAnalyticsResponse 

type MagicLinkAnalyticsResponse struct {
	Sent                    int            `json:"sent,omitempty"`
	Verified                int            `json:"verified,omitempty"`
	Expired                 int            `json:"expired,omitempty"`
	Stats                   map[string]any `json:"stats,omitempty"`
	AverageVerificationTime int64          `json:"average_verification_time,omitempty"`
	RecentActivity          []string       `json:"recent_activity,omitempty"`
	TopDomains              []string       `json:"top_domains,omitempty"`
	TotalSentThisWeek       int64          `json:"total_sent_this_week,omitempty"`
	TotalSentToday          int64          `json:"total_sent_today,omitempty"`
	TotalVerified           int64          `json:"total_verified,omitempty"`
}

MagicLinkAnalyticsResponse is the result of GET .../magic-link/analytics.

type MagicLinkConfigResponse 

type MagicLinkConfigResponse struct {
	Enabled         bool  `json:"enabled,omitempty"`
	TTLSeconds      int   `json:"ttl_seconds,omitempty"`
	MaxActive       int   `json:"max_active,omitempty"`
	CooldownSeconds int64 `json:"cooldown_seconds,omitempty"`
	ExpiryMinutes   int64 `json:"expiry_minutes,omitempty"`
	MaxAttempts     int64 `json:"max_attempts,omitempty"`
	RequireCode     bool  `json:"require_code,omitempty"`
}

MagicLinkConfigResponse is the result of GET .../magic-link/config.

type MagicLinkSendResponse 

type MagicLinkSendResponse struct {
	Message   string `json:"message,omitempty"`
	Success   bool   `json:"success,omitempty"`
	ExpiresIn int    `json:"expires_in,omitempty"`
}

MagicLinkSendResponse is the result of sending a magic link.

type MeshConsumerRegistration 

type MeshConsumerRegistration struct {
	Enabled     bool               `json:"enabled,omitempty"`
	OrgSlug     string             `json:"org_slug,omitempty"`
	RegisterURL string             `json:"register_url,omitempty"`
	Tiers       []MeshProviderTier `json:"tiers,omitempty"`
}

MeshConsumerRegistration describes how a consumer signs up to a provider.

type MeshProvider 

type MeshProvider struct {
	ServiceID            string                    `json:"service_id,omitempty"`
	DisplayName          string                    `json:"display_name,omitempty"`
	ConsumerRegistration *MeshConsumerRegistration `json:"consumer_registration,omitempty"`
	DocsURL              string                    `json:"docs_url,omitempty"`
	// ConnectPrompt is the natural-language instruction an agent can follow to
	// connect to this provider.
	ConnectPrompt string `json:"connect_prompt,omitempty"`
	SchemaURL     string `json:"schema_url,omitempty"`
	// LLMsTxtURL points at the provider's llms.txt (agent-facing description).
	LLMsTxtURL    string `json:"llms_txt_url,omitempty"`
	SupportURL    string `json:"support_url,omitempty"`
	QuickstartURL string `json:"quickstart_url,omitempty"`
	UpdatedAt     string `json:"updated_at,omitempty"`
}

MeshProvider is a published provider entry in the mesh directory. Matches OpenAPI schema MeshProvider (no required fields — the server may return a sparse entry, so treat every field as optional).

type MeshProviderPublishRequest 

type MeshProviderPublishRequest struct {
	ServiceID   string `json:"service_id"`
	DisplayName string `json:"display_name"`
	// RegisterURL is where a consumer goes to sign up.
	RegisterURL string `json:"register_url"`
	OrgSlug     string `json:"org_slug"`

	Tiers         []MeshProviderTierInput `json:"tiers,omitempty"`
	SignupEnabled bool                    `json:"signup_enabled,omitempty"`

	DocsURL       string `json:"docs_url,omitempty"`
	ConnectPrompt string `json:"connect_prompt,omitempty"`
	SchemaURL     string `json:"schema_url,omitempty"`
	LLMsTxtURL    string `json:"llms_txt_url,omitempty"`
	SupportURL    string `json:"support_url,omitempty"`
	QuickstartURL string `json:"quickstart_url,omitempty"`

	// PublicMesh lists the provider in the PUBLIC directory. Leaving it false
	// publishes privately.
	PublicMesh bool `json:"public_mesh,omitempty"`
	// PrivilegedPerms declares permissions the publisher knows are privileged.
	PrivilegedPerms []string `json:"privileged_perms,omitempty"`
}

MeshProviderPublishRequest is the body for POST /mesh/providers. Matches OpenAPI schema MeshProviderPublishRequest (required: service_id, display_name, register_url, org_slug).

type MeshProviderPublishResponse 

type MeshProviderPublishResponse struct {
	Valid     bool   `json:"valid"`
	ServiceID string `json:"service_id,omitempty"`
	Listed    bool   `json:"listed,omitempty"`
	Reason    string `json:"reason,omitempty"`

	// DocsURLWarning reports that the docs URL looked unreachable or malformed.
	DocsURLWarning bool `json:"docs_url_warning,omitempty"`
	// PrivilegeWarning reports that a declared tier grants privileged
	// permissions; PrivilegeViolations names them.
	PrivilegeWarning    bool     `json:"privilege_warning,omitempty"`
	PrivilegeViolations []string `json:"privilege_violations,omitempty"`
}

MeshProviderPublishResponse is the result of POST /mesh/providers. Matches OpenAPI schema MeshProviderPublishResponse (required: valid).

NOTE the shape of the contract: a 200 does NOT mean "published". Valid reports whether the submission was accepted and Listed whether it actually appears in the directory; Reason carries the explanation when it does not. Always check Valid and Listed rather than relying on the absence of an error.

type MeshProviderTier 

type MeshProviderTier struct {
	Name string `json:"name"`
	// Default marks the tier a consumer gets if it does not choose one.
	Default bool `json:"default,omitempty"`
	// PermissionCount is server-computed; it is not settable on publish.
	PermissionCount int      `json:"permission_count,omitempty"`
	Permissions     []string `json:"permissions,omitempty"`
	// PrivilegedAck records that the publisher explicitly acknowledged that this
	// tier grants privileged permissions.
	PrivilegedAck bool `json:"privileged_ack,omitempty"`
}

MeshProviderTier is one named permission tier a provider offers, as returned by a read. Matches OpenAPI schema MeshProviderTier (required: name).

type MeshProviderTierInput 

type MeshProviderTierInput struct {
	Name          string   `json:"name"`
	Default       bool     `json:"default,omitempty"`
	Permissions   []string `json:"permissions,omitempty"`
	PrivilegedAck bool     `json:"privileged_ack,omitempty"`
}

MeshProviderTierInput is a tier as supplied on publish. It is deliberately a separate type from MeshProviderTier: PermissionCount is server-computed and sending it is meaningless.

type MeshProvidersListResponse 

type MeshProvidersListResponse struct {
	Providers []MeshProvider `json:"providers,omitempty"`
}

MeshProvidersListResponse is the result of GET /mesh/providers.

type MessageDetailResponse 

type MessageDetailResponse struct {
	Message string `json:"message,omitempty"`
	Success bool   `json:"success,omitempty"`
	Status  string `json:"status,omitempty"`
	UserID  string `json:"user_id,omitempty"`
}

MessageDetailResponse adds a structured detail/status to a message (used by user activate/deactivate).

type MessageResponse 

type MessageResponse struct {
	Message string `json:"message,omitempty"`
	Success bool   `json:"success,omitempty"`
}

MessageResponse is the generic {"message": ...} envelope returned by many mutating endpoints across the auth service.

type NamespaceDetailResponse 

type NamespaceDetailResponse struct {
	Name            string         `json:"name"`
	Relations       map[string]any `json:"relations,omitempty"`
	Permissions     map[string]any `json:"permissions,omitempty"`
	ParentNamespace string         `json:"parent_namespace,omitempty"`
	Metadata        map[string]any `json:"metadata,omitempty"`
	Version         *int           `json:"version,omitempty"`
}

NamespaceDetailResponse is one namespace's full definition. Matches OpenAPI schema NamespaceDetailResponse (required: name).

type NamespaceListResponse 

type NamespaceListResponse struct {
	Namespaces []NamespaceSummary `json:"namespaces,omitempty"`
}

NamespaceListResponse lists the namespaces in a store. Matches OpenAPI schema NamespaceListResponse.

type NamespaceRequest 

type NamespaceRequest struct {
	Name            string         `json:"name"`
	Relations       map[string]any `json:"relations"`
	Permissions     map[string]any `json:"permissions"`
	ParentNamespace string         `json:"parent_namespace,omitempty"`
	Metadata        map[string]any `json:"metadata,omitempty"`
}

NamespaceRequest is the body for POST /zanzibar/stores/{store_id}/namespaces. Matches OpenAPI schema NamespaceRequest (required: name, relations, permissions). Relations and Permissions are the namespace's relation and permission (userset-rewrite) definitions.

type NamespaceSummary 

type NamespaceSummary struct {
	Name            string   `json:"name"`
	Relations       []string `json:"relations,omitempty"`
	Permissions     []string `json:"permissions,omitempty"`
	ParentNamespace string   `json:"parent_namespace,omitempty"`
	Version         *int     `json:"version,omitempty"`
}

NamespaceSummary is one entry of a namespace listing. Matches OpenAPI schema NamespaceSummary (required: name).

type NetworkOverride 

type NetworkOverride struct {
	ID        string `json:"id"`
	IP        string `json:"ip,omitempty"`
	Reason    string `json:"reason,omitempty"`
	CreatedAt string `json:"created_at,omitempty"`
	ExpiresAt string `json:"expires_at,omitempty"`
}

NetworkOverride is one emergency override entry.

type NetworkPolicy 

type NetworkPolicy struct {
	PolicyID              string   `json:"policy_id,omitempty"`
	OrgID                 string   `json:"org_id,omitempty"`
	Name                  string   `json:"name,omitempty"`
	Description           string   `json:"description,omitempty"`
	Priority              int      `json:"priority,omitempty"`
	Enabled               bool     `json:"enabled,omitempty"`
	Action                string   `json:"action,omitempty"`
	Networks              []string `json:"networks,omitempty"`
	GeoCountries          []string `json:"geo_countries,omitempty"`
	GeoMode               string   `json:"geo_mode,omitempty"`
	RestrictedPermissions []string `json:"restricted_permissions,omitempty"`
	RequireMFA            bool     `json:"require_mfa,omitempty"`
	CreatedBy             string   `json:"created_by,omitempty"`
	CreatedAt             string   `json:"created_at,omitempty"`
	UpdatedAt             string   `json:"updated_at,omitempty"`
	ExpiresAt             string   `json:"expires_at,omitempty"`
}

NetworkPolicy is an IP/network access policy. "networks" are CIDRs; "action" is allow|deny (the server vocabulary), not the old allowlist|blocklist "mode".

type NetworkPolicyCreateResponse 

type NetworkPolicyCreateResponse struct {
	PolicyID  string `json:"policy_id"`
	Message   string `json:"message,omitempty"`
	Action    string `json:"action,omitempty"`
	CreatedAt string `json:"created_at,omitempty"`
	Name      string `json:"name,omitempty"`
	OrgID     string `json:"org_id,omitempty"`
	Status    string `json:"status,omitempty"`
}

NetworkPolicyCreateResponse is the result of creating a network policy.

type NetworkPolicyListResponse 

type NetworkPolicyListResponse struct {
	Policies []NetworkPolicy `json:"policies"`
	Total    int             `json:"total,omitempty"`
	Count    int64           `json:"count,omitempty"`
}

NetworkPolicyListResponse lists network policies.

type NetworkPolicyStatusResponse 

type NetworkPolicyStatusResponse struct {
	Success    bool   `json:"success,omitempty"`
	Message    string `json:"message,omitempty"`
	Status     string `json:"status,omitempty"`
	EntryID    string `json:"entry_id,omitempty"`
	OverrideID string `json:"override_id,omitempty"`
	PolicyID   string `json:"policy_id,omitempty"`
}

NetworkPolicyStatusResponse is the generic status envelope for update/delete/override/allowlist mutations.

type NetworkViolation 

type NetworkViolation struct {
	IP        string `json:"ip,omitempty"`
	PolicyID  string `json:"policy_id,omitempty"`
	Path      string `json:"path,omitempty"`
	Timestamp string `json:"timestamp,omitempty"`
	Reason    string `json:"reason,omitempty"`
}

NetworkViolation is one recorded access violation.

type NextRotationResponse 

type NextRotationResponse struct {
	NextRotation      string `json:"next_rotation,omitempty"`
	CurrentKeyAgeDays int64  `json:"current_key_age_days,omitempty"`
	DaysUntilRotation int64  `json:"days_until_rotation,omitempty"`
	NextRotationDate  string `json:"next_rotation_date,omitempty"`
	RotationNeeded    bool   `json:"rotation_needed,omitempty"`
	Timestamp         string `json:"timestamp,omitempty"`
}

NextRotationResponse is the result of GET /admin/jwks/next-rotation.

type OAuthAuthorize 

type OAuthAuthorize struct {
	AuthorizationURL string `json:"authorization_url"`
	State            string `json:"state,omitempty"`
	Provider         string `json:"provider,omitempty"`
	// CodeVerifier is returned only when the server generated PKCE on the
	// caller's behalf; otherwise empty.
	CodeVerifier string `json:"code_verifier,omitempty"`
}

OAuthAuthorize is the result of starting an OAuth/OIDC flow (OAuthProviderAuthorizeResponse). AuthorizationURL is where the caller should redirect the user-agent.

type OAuthAuthorizeParams 

type OAuthAuthorizeParams struct {
	// Provider is the upstream IdP identifier (e.g. "google", "okta").
	Provider string `json:"-"`
	// RedirectURI is where the IdP returns the user after consent.
	RedirectURI string `json:"redirect_uri,omitempty"`
	// State is an opaque CSRF token echoed back to the callback.
	State string `json:"state,omitempty"`
	// Scope is a space-delimited list of requested scopes.
	Scope string `json:"scope,omitempty"`
	// OrgID scopes the flow to a specific organization/tenant.
	OrgID string `json:"org_id,omitempty"`
	// CodeChallenge / CodeChallengeMethod enable PKCE.
	CodeChallenge       string `json:"code_challenge,omitempty"`
	CodeChallengeMethod string `json:"code_challenge_method,omitempty"`
	// LoginHint pre-fills the IdP login (e.g. an email).
	LoginHint string `json:"login_hint,omitempty"`
}

OAuthAuthorizeParams configures the start of an OAuth2/OIDC authorization (GET /auth/oauth/{provider}/authorize). Fields map to standard OAuth2 query parameters; zero-valued fields are omitted.

type OAuthCallbackParams 

type OAuthCallbackParams struct {
	Provider     string `json:"-"`
	Code         string `json:"code,omitempty"`
	State        string `json:"state,omitempty"`
	RedirectURI  string `json:"redirect_uri,omitempty"`
	CodeVerifier string `json:"code_verifier,omitempty"`
	// Error / ErrorDescription are populated when the IdP denied the request.
	Error            string `json:"error,omitempty"`
	ErrorDescription string `json:"error_description,omitempty"`
}

OAuthCallbackParams carries the values returned by the IdP to the callback endpoint (POST /auth/oauth/{provider}/callback). They are sent as form values.

type OAuthProviderAuthorizeResponse 

type OAuthProviderAuthorizeResponse struct {
	AuthorizationURL string `json:"authorization_url,omitempty"`
	Provider         string `json:"provider,omitempty"`
	State            string `json:"state,omitempty"`
}

OAuthProviderAuthorizeResponse is returned by GET /auth/oauth/{provider}/authorize.

type Observer added in v0.5.0 

type Observer func(RequestInfo)

Observer is called once per completed HTTP attempt.

It runs on the calling goroutine, inside the request path, so it must be fast and must not block — a slow observer slows every request. It must also be safe for concurrent use if the client is shared, which it is designed to be.

A panic in an Observer is NOT recovered. That is deliberate: swallowing it would hide a bug in consumer code at the exact place a consumer is least likely to look, and a panic in an observability hook should be as loud as any other.

type OpenIDConfiguration 

type OpenIDConfiguration struct {
	Issuer                                     string          `json:"issuer"`
	AuthorizationEndpoint                      string          `json:"authorization_endpoint,omitempty"`
	TokenEndpoint                              string          `json:"token_endpoint,omitempty"`
	UserinfoEndpoint                           string          `json:"userinfo_endpoint,omitempty"`
	JWKSURI                                    string          `json:"jwks_uri,omitempty"`
	RegistrationEndpoint                       string          `json:"registration_endpoint,omitempty"`
	ScopesSupported                            []string        `json:"scopes_supported,omitempty"`
	ResponseTypesSupported                     []string        `json:"response_types_supported,omitempty"`
	GrantTypesSupported                        []string        `json:"grant_types_supported,omitempty"`
	SubjectTypesSupported                      []string        `json:"subject_types_supported,omitempty"`
	IDTokenSigningAlgValuesSupported           []string        `json:"id_token_signing_alg_values_supported,omitempty"`
	TokenEndpointAuthMethodsSupported          []string        `json:"token_endpoint_auth_methods_supported,omitempty"`
	CodeChallengeMethodsSupported              []string        `json:"code_challenge_methods_supported,omitempty"`
	AuthorizationDetailsTypesSupported         []string        `json:"authorization_details_types_supported,omitempty"`
	ClaimsParameterSupported                   bool            `json:"claims_parameter_supported,omitempty"`
	ClaimsSupported                            []string        `json:"claims_supported,omitempty"`
	DPoPSigningAlgValuesSupported              []string        `json:"dpop_signing_alg_values_supported,omitempty"`
	Features                                   json.RawMessage `json:"features,omitempty"`
	IntrospectionEndpoint                      string          `json:"introspection_endpoint,omitempty"`
	IntrospectionEndpointAuthMethodsSupported  []string        `json:"introspection_endpoint_auth_methods_supported,omitempty"`
	JWKSRefreshInterval                        int64           `json:"jwks_refresh_interval,omitempty"`
	JWKSSupportsProviderAggregation            bool            `json:"jwks_supports_provider_aggregation,omitempty"`
	KeyRotationInterval                        int64           `json:"key_rotation_interval,omitempty"`
	OpPolicyURI                                string          `json:"op_policy_uri,omitempty"`
	OpTOSURI                                   string          `json:"op_tos_uri,omitempty"`
	PushedAuthorizationRequestEndpoint         string          `json:"pushed_authorization_request_endpoint,omitempty"`
	RequestParameterSupported                  bool            `json:"request_parameter_supported,omitempty"`
	RequestURIParameterSupported               bool            `json:"request_uri_parameter_supported,omitempty"`
	RequirePushedAuthorizationRequests         bool            `json:"require_pushed_authorization_requests,omitempty"`
	RequireRequestURIRegistration              bool            `json:"require_request_uri_registration,omitempty"`
	ResponseModesSupported                     []string        `json:"response_modes_supported,omitempty"`
	RevocationEndpoint                         string          `json:"revocation_endpoint,omitempty"`
	RevocationEndpointAuthMethodsSupported     []string        `json:"revocation_endpoint_auth_methods_supported,omitempty"`
	ServiceDocumentation                       string          `json:"service_documentation,omitempty"`
	TokenEndpointAuthSigningAlgValuesSupported []string        `json:"token_endpoint_auth_signing_alg_values_supported,omitempty"`
	UiLocalesSupported                         []string        `json:"ui_locales_supported,omitempty"`
}

OpenIDConfiguration is the OIDC discovery document.

type Option 

type Option func(*Client)

Option configures a Client.

func WithAPIKey 

func WithAPIKey(key string) Option

WithAPIKey sets the service API key (prefix "ab0t_sk_") used on calls that require service-to-service auth (e.g. CheckPermission). It is transported as X-API-Key — the header every API-key-accepting surface reads; see CredentialHeader for why not Authorization: Bearer. Per-call user tokens always override this default.

func WithBackoff 

func WithBackoff(base, max time.Duration) Option

WithBackoff configures the exponential backoff used between retries. base is the initial delay; max caps the per-attempt delay. The transport honors a Retry-After header on 429/503 responses when present.

func WithBaseURL 

func WithBaseURL(u string) Option

WithBaseURL overrides the auth service base URL.

func WithExpectedAudience 

func WithExpectedAudience(aud string) Option

WithExpectedAudience sets a default `aud` assertion applied to token/api-key validation, ensuring tokens were minted for this service.

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient supplies a custom *http.Client (transport, proxy, etc.). If the supplied client has a zero Timeout, the default timeout is applied.

func WithMaxRetries 

func WithMaxRetries(n int) Option

WithMaxRetries sets how many times a retryable request (idempotent GET, or any request returning 429/5xx) is retried with exponential backoff. 0 disables retries.

func WithObserver added in v0.5.0 

func WithObserver(fn Observer) Option

WithObserver installs a callback invoked once per completed HTTP attempt. 

client := authclient.New("", authclient.WithObserver(func(i authclient.RequestInfo) {
    slog.Info("auth call",
        "method", i.Method, "endpoint", i.Endpoint, "status", i.Status,
        "ms", i.Duration.Milliseconds(), "attempt", i.Attempt, "err", i.Err)
}))

Passing nil clears any previously set observer. With none set the client behaves exactly as before — the hook is not consulted at all.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets the per-request timeout enforced via the http.Client. A non-positive value disables the client-level timeout (callers should then rely on context deadlines).

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header.

func WithValidationCache added in v0.10.0 

func WithValidationCache(ttl time.Duration) Option

WithValidationCache enables an in-process TTL cache for ValidateToken, ValidateTokenWith, ValidateAPIKey and Authorize, using ttl for positive decisions and the package defaults for everything else.

A non-positive ttl disables the cache — that is the documented way to turn it off, including in a config-driven service that wants the knob to exist. 

client := authclient.New("", authclient.WithValidationCache(authclient.DefaultValidationCacheTTL))

READ THIS BEFORE ENABLING. The TTL is the maximum time a revoked credential, a removed permission, or a deleted API key can continue to be accepted by this process. Choose it against your revocation requirement, not against your latency target, and call InvalidateValidation when you revoke something you know about locally.

func WithValidationCacheOptions added in v0.10.0 

func WithValidationCacheOptions(o ValidationCacheOptions) Option

WithValidationCacheOptions is WithValidationCache with full control over the negative TTL and the entry bound.

type OrgClientSafe 

type OrgClientSafe struct {
	ClientID     string   `json:"client_id"`
	ClientName   string   `json:"client_name,omitempty"`
	RedirectURIs []string `json:"redirect_uris,omitempty"`
	GrantTypes   []string `json:"grant_types,omitempty"`
	CreatedAt    string   `json:"created_at,omitempty"`
}

OrgClientSafe is the safe (non-secret) view of an OAuth client in an org.

type OrgClientSafeResponse 

type OrgClientSafeResponse struct {
	Clients []OrgClientSafe `json:"clients"`
	Total   int             `json:"total,omitempty"`
}

OrgClientSafeResponse is the result of GET /organizations/{org_id}/clients.

type OrgEmailConfig 

type OrgEmailConfig struct {
	Provider    string         `json:"provider,omitempty"`
	FromAddress string         `json:"from_address,omitempty"`
	FromName    string         `json:"from_name,omitempty"`
	ReplyTo     string         `json:"reply_to,omitempty"`
	Settings    map[string]any `json:"settings,omitempty"`
}

OrgEmailConfig is a per-organisation email configuration.

type OrgEmailConfigResponse 

type OrgEmailConfigResponse struct {
	Config OrgEmailConfig `json:"config"`
}

OrgEmailConfigResponse wraps an org's email configuration.

type OrgEmailConfigUpdate 

type OrgEmailConfigUpdate struct {
	Provider    *string         `json:"provider,omitempty"`
	FromAddress *string         `json:"from_address,omitempty"`
	FromName    *string         `json:"from_name,omitempty"`
	ReplyTo     *string         `json:"reply_to,omitempty"`
	APIKey      *string         `json:"api_key,omitempty"`
	Settings    *map[string]any `json:"settings,omitempty"`
}

OrgEmailConfigUpdate is the body for PUT /organizations/{org_id}/emails/config.

type OrgEmailTemplate 

type OrgEmailTemplate struct {
	Type     string `json:"type,omitempty"`
	Subject  string `json:"subject,omitempty"`
	HTMLBody string `json:"html_body,omitempty"`
	TextBody string `json:"text_body,omitempty"`
	Enabled  bool   `json:"enabled,omitempty"`
}

OrgEmailTemplate is a per-organisation email template.

type OrgEmailTemplateResponse 

type OrgEmailTemplateResponse struct {
	Template  *OrgEmailTemplate  `json:"template,omitempty"`
	Templates []OrgEmailTemplate `json:"templates,omitempty"`
}

OrgEmailTemplateResponse wraps one or more org email templates.

type OrgEmailTemplateUpdate 

type OrgEmailTemplateUpdate struct {
	Subject  *string `json:"subject,omitempty"`
	HTMLBody *string `json:"html_body,omitempty"`
	TextBody *string `json:"text_body,omitempty"`
	Enabled  *bool   `json:"enabled,omitempty"`
}

OrgEmailTemplateUpdate is the body for updating an org email template.

type OrgHierarchyNode 

type OrgHierarchyNode struct {
	ID       string             `json:"id"`
	Name     string             `json:"name"`
	Slug     string             `json:"slug,omitempty"`
	ParentID string             `json:"parent_id,omitempty"`
	Type     string             `json:"type,omitempty"`
	Children []OrgHierarchyNode `json:"children,omitempty"`
}

OrgHierarchyNode is a node in an organization tree.

type OrgHierarchyRequest 

type OrgHierarchyRequest struct {
	OrgID       string `json:"org_id"`
	ParentOrgID string `json:"parent_org_id,omitempty"`
	WorkspaceID string `json:"workspace_id,omitempty"`
}

OrgHierarchyRequest is the body for POST /zanzibar/stores/{store_id}/hierarchy/setup. Matches OpenAPI schema OrgHierarchyRequest (required: org_id).

type OrgHierarchyResponse 

type OrgHierarchyResponse struct {
	Organization *OrgInfo               `json:"organization"`
	Teams        []HierarchyTeam        `json:"teams,omitempty"`
	Children     []OrgHierarchyResponse `json:"children,omitempty"`
	UserCount    int                    `json:"user_count,omitempty"`
	TeamCount    int                    `json:"team_count,omitempty"`
}

OrgHierarchyResponse is the result of GET /organizations/{org_id}/hierarchy.

CONTRACT NOTE: an earlier release of this SDK declared this as {root, organizations}, which no version of the service has ever returned — the spec defines {organization, teams, children, user_count, team_count} with `organization` required. Every field would have decoded to its zero value, and silently: JSON decoding does not complain about names it does not recognise, so a caller got an empty tree rather than an error. This is the same class of defect as the bulk-check mismatch fixed in v0.2.0, and the reason `make drift` exists.

Children are the SUB-ORGANIZATIONS: this is how companies-of-companies are represented on the wire.

func (*OrgHierarchyResponse) WalkOrgTree added in v0.9.0 

func (r *OrgHierarchyResponse) WalkOrgTree(fn func(node *OrgHierarchyResponse, depth int))

WalkOrgTree visits every organization in the hierarchy depth-first, including the root, calling fn with the node and its depth.

Provided because "how many companies are under this one" and "flatten the tree for an audit" are the two things every caller does with this response, and both are recursive — which is exactly the code people get subtly wrong.

type OrgInfo added in v0.9.0 

type OrgInfo struct {
	ID       string `json:"id,omitempty"`
	Name     string `json:"name,omitempty"`
	Slug     string `json:"slug,omitempty"`
	ParentID string `json:"parent_id,omitempty"`
	Domain   string `json:"domain,omitempty"`
	Status   string `json:"status,omitempty"`

	BillingType string `json:"billing_type,omitempty"`
	Industry    string `json:"industry,omitempty"`
	Size        string `json:"size,omitempty"`
	Timezone    string `json:"timezone,omitempty"`
	Website     string `json:"website,omitempty"`
	LogoURL     string `json:"logo_url,omitempty"`
	CreatedAt   string `json:"created_at,omitempty"`
	UpdatedAt   string `json:"updated_at,omitempty"`
}

OrgInfo describes one organization in a hierarchy response.

ParentID is the nesting primitive: organizations form a TREE. A company can own sub-companies, each with their own teams and users. Nothing in this SDK exposed that before, so consumers modelled a flat tenancy the service never had.

type OrgLoginRequest 

type OrgLoginRequest struct {
	Email    string `json:"email"`
	Password string `json:"password"`
}

OrgLoginRequest is the body for POST /organizations/{slug}/auth/login.

type OrgMember 

type OrgMember struct {
	UserID      string   `json:"user_id"`
	Email       string   `json:"email,omitempty"`
	Name        string   `json:"name,omitempty"`
	Role        string   `json:"role,omitempty"`
	Status      string   `json:"status,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
	JoinedAt    string   `json:"joined_at,omitempty"`
}

OrgMember is one organization membership entry.

type OrgPasswordResetRequest 

type OrgPasswordResetRequest struct {
	Email string `json:"email"`
}

OrgPasswordResetRequest is the body for POST /organizations/{slug}/auth/reset-password.

type OrgProviderInfo 

type OrgProviderInfo struct {
	ID       string `json:"id"`
	Type     string `json:"type,omitempty"`
	Name     string `json:"name,omitempty"`
	Priority int    `json:"priority,omitempty"`
}

OrgProviderInfo is the safe provider metadata returned to a hosted login page.

type OrgProvidersResponse 

type OrgProvidersResponse struct {
	Providers []OrgProviderInfo `json:"providers"`
}

OrgProvidersResponse is the result of GET /organizations/{slug}/auth/providers.

type OrgRegisterRequest 

type OrgRegisterRequest struct {
	Email     string `json:"email"`
	Password  string `json:"password"`
	Name      string `json:"name,omitempty"`
	FirstName string `json:"first_name,omitempty"`
	LastName  string `json:"last_name,omitempty"`
}

OrgRegisterRequest is the body for POST /organizations/{slug}/auth/register.

type OrgRoleUpdate 

type OrgRoleUpdate struct {
	Role        string   `json:"role,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
}

OrgRoleUpdate is the body for PUT /organizations/{org_id}/users/{user_id}.

type OrgSession 

type OrgSession struct {
	ID         string `json:"id"`
	UserID     string `json:"user_id"`
	IPAddress  string `json:"ip_address,omitempty"`
	UserAgent  string `json:"user_agent,omitempty"`
	CreatedAt  string `json:"created_at,omitempty"`
	LastSeenAt string `json:"last_seen_at,omitempty"`
	ExpiresAt  string `json:"expires_at,omitempty"`
}

OrgSession is one active session row.

type OrgSessionsResponse 

type OrgSessionsResponse struct {
	Sessions []OrgSession `json:"sessions"`
	Total    int          `json:"total,omitempty"`
}

OrgSessionsResponse is the result of GET /organizations/{org_id}/sessions.

type OrgUserResponse 

type OrgUserResponse struct {
	Users []OrgMember `json:"users"`
	Total int         `json:"total,omitempty"`
}

OrgUserResponse is the result of GET /organizations/{org_id}/users.

type Organization 

type Organization struct {
	ID              string         `json:"id"`
	Name            string         `json:"name"`
	Slug            string         `json:"slug,omitempty"`
	Domain          string         `json:"domain,omitempty"`
	ParentID        string         `json:"parent_id,omitempty"`
	ServiceAudience string         `json:"service_audience,omitempty"`
	BillingType     string         `json:"billing_type,omitempty"`
	Status          string         `json:"status,omitempty"`
	Timezone        string         `json:"timezone,omitempty"`
	Settings        map[string]any `json:"settings,omitempty"`
	Metadata        map[string]any `json:"metadata,omitempty"`
	CreatedAt       string         `json:"created_at,omitempty"`
	Industry        string         `json:"industry,omitempty"`
	LogoURL         string         `json:"logo_url,omitempty"`
	Size            string         `json:"size,omitempty"`
	UpdatedAt       string         `json:"updated_at,omitempty"`
	Website         string         `json:"website,omitempty"`
}

Organization is the result of GET /organizations/{org_id}.

type OrganizationCreate 

type OrganizationCreate struct {
	Name            string         `json:"name"`
	Slug            string         `json:"slug,omitempty"`
	Domain          string         `json:"domain,omitempty"`
	ParentID        string         `json:"parent_id,omitempty"`
	BillingType     string         `json:"billing_type,omitempty"`
	ServiceAudience string         `json:"service_audience,omitempty"`
	Timezone        string         `json:"timezone,omitempty"`
	Settings        map[string]any `json:"settings,omitempty"`
	Metadata        map[string]any `json:"metadata,omitempty"`
}

OrganizationCreate is the body for POST /organizations/.

type OrganizationInvite 

type OrganizationInvite struct {
	Email   string   `json:"email"`
	Role    string   `json:"role,omitempty"`
	TeamIDs []string `json:"team_ids,omitempty"`
	Message string   `json:"message,omitempty"`
	Resend  bool     `json:"resend,omitempty"`
}

OrganizationInvite is the body for POST /organizations/{org_id}/invite.

type OrganizationUpdate 

type OrganizationUpdate struct {
	Name        *string         `json:"name,omitempty"`
	Domain      *string         `json:"domain,omitempty"`
	BillingType *string         `json:"billing_type,omitempty"`
	Status      *string         `json:"status,omitempty"`
	Timezone    *string         `json:"timezone,omitempty"`
	Settings    *map[string]any `json:"settings,omitempty"`
	Metadata    *map[string]any `json:"metadata,omitempty"`
}

OrganizationUpdate is the body for PUT /organizations/{org_id}.

type OverrideListResponse 

type OverrideListResponse struct {
	Overrides []NetworkOverride `json:"overrides"`
	Count     int64             `json:"count,omitempty"`
}

OverrideListResponse lists emergency overrides.

type PasswordAgeUpdate 

type PasswordAgeUpdate struct {
	UserID  string `json:"user_id"`
	AgeDays int    `json:"age_days"`
}

PasswordAgeUpdate is the body for POST /admin/users/password-age (test helper).

type PasswordAgeUpdateResponse 

type PasswordAgeUpdateResponse struct {
	Message string `json:"message,omitempty"`
	UserID  string `json:"user_id,omitempty"`
	AgeDays int64  `json:"age_days,omitempty"`
}

PasswordAgeUpdateResponse is the result of POST /admin/users/password-age.

type PasswordAuditEventsResponse 

type PasswordAuditEventsResponse struct {
	Events      []map[string]any `json:"events"`
	Total       int              `json:"total,omitempty"`
	AuditEvents json.RawMessage  `json:"audit_events,omitempty"`
}

PasswordAuditEventsResponse is the result of GET /admin/audit/password-events.

type PasswordComplianceResponse 

type PasswordComplianceResponse struct {
	Compliant        int             `json:"compliant,omitempty"`
	NonCompliant     int             `json:"non_compliant,omitempty"`
	Details          map[string]any  `json:"details,omitempty"`
	ComplianceReport json.RawMessage `json:"compliance_report,omitempty"`
	OrgID            string          `json:"org_id,omitempty"`
}

PasswordComplianceResponse is the result of GET /admin/reports/password-compliance.

type PasswordPolicyGetResponse 

type PasswordPolicyGetResponse struct {
	OrgID  string                 `json:"org_id,omitempty"`
	Policy *PasswordPolicyRequest `json:"policy,omitempty"`
}

PasswordPolicyGetResponse is the result of GET /admin/password-policy/{org_id}.

type PasswordPolicyRequest 

type PasswordPolicyRequest struct {
	OrgID            string `json:"org_id,omitempty"`
	MinLength        int    `json:"min_length,omitempty"`
	RequireUppercase bool   `json:"require_uppercase,omitempty"`
	RequireLowercase bool   `json:"require_lowercase,omitempty"`
	RequireNumbers   bool   `json:"require_numbers,omitempty"`
	RequireSymbols   bool   `json:"require_symbols,omitempty"`
	MaxAgeDays       int    `json:"max_age_days,omitempty"`
	HistoryCount     int    `json:"history_count,omitempty"`
}

PasswordPolicyRequest is the body for POST /admin/password-policy.

type PasswordPolicySetResponse 

type PasswordPolicySetResponse struct {
	Message  string                 `json:"message,omitempty"`
	Policy   *PasswordPolicyRequest `json:"policy,omitempty"`
	PolicyID string                 `json:"policy_id,omitempty"`
}

PasswordPolicySetResponse is the result of setting a password policy.

type PasswordReset 

type PasswordReset struct {
	Email string `json:"email"`
	OrgID string `json:"org_id,omitempty"`
}

PasswordReset is the body for POST /users/request-password-reset, POST /auth/password-reset, and POST /auth/check-permission's reset flows.

type PasswordResetConfirm 

type PasswordResetConfirm struct {
	Token       string `json:"token"`
	NewPassword string `json:"new_password"`
}

PasswordResetConfirm is the body for POST /users/reset-password and POST /auth/password-reset/confirm.

type PasswordResetConfirmResponse 

type PasswordResetConfirmResponse struct {
	Message string `json:"message,omitempty"`
	Success bool   `json:"success,omitempty"`
	Detail  string `json:"detail,omitempty"`
}

PasswordResetConfirmResponse is the result of confirming a password reset.

type PasswordResetResponse 

type PasswordResetResponse struct {
	Message string `json:"message,omitempty"`
	Success bool   `json:"success,omitempty"`
	Detail  string `json:"detail,omitempty"`
	Note    string `json:"note,omitempty"`
}

PasswordResetResponse is the result of requesting a password reset.

type PasswordResetValidateResponse 

type PasswordResetValidateResponse struct {
	Valid   bool   `json:"valid"`
	Email   string `json:"email,omitempty"`
	Message string `json:"message,omitempty"`
}

PasswordResetValidateResponse is the result of validating a reset token.

type PasswordlessAuthResponse 

type PasswordlessAuthResponse struct {
	AccessToken  string            `json:"access_token,omitempty"`
	RefreshToken string            `json:"refresh_token,omitempty"`
	TokenType    string            `json:"token_type,omitempty"`
	ExpiresIn    int               `json:"expires_in,omitempty"`
	User         *TokenUserInfo    `json:"user,omitempty"`
	CustomClaims map[string]string `json:"custom_claims,omitempty"`
	RedirectURL  string            `json:"redirect_url,omitempty"`
}

PasswordlessAuthResponse is the token payload returned by a successful passwordless authentication (WebAuthn, magic link or recovery code).

type PermissionCheckRequest 

type PermissionCheckRequest struct {
	UserID       string `json:"user_id"`
	Permission   string `json:"permission"`
	OrgID        string `json:"org_id,omitempty"`
	ResourceType string `json:"resource_type,omitempty"`
	ResourceID   string `json:"resource_id,omitempty"`
}

PermissionCheckRequest is the body for POST /permissions/check and POST /auth/check-permission.

type PermissionDecision 

type PermissionDecision struct {
	Allowed              bool     `json:"allowed"`
	Reason               string   `json:"reason,omitempty"`
	Source               string   `json:"source,omitempty"`
	EffectivePermissions []string `json:"effective_permissions,omitempty"`
	// Scope reports how broadly the grant matched (e.g. object-scoped vs
	// wider); returned by the permission check response.
	Scope string `json:"scope,omitempty"`
}

PermissionDecision is the result of a permission check.

type PermissionGrantRequest 

type PermissionGrantRequest struct {
	Subject    string         `json:"subject"`
	Permission string         `json:"permission"`
	Resource   string         `json:"resource"`
	ExpiresAt  *time.Time     `json:"expires_at,omitempty"`
	Conditions map[string]any `json:"conditions,omitempty"`
}

PermissionGrantRequest is the body for POST/DELETE /zanzibar/stores/{store_id}/permissions/{grant,revoke}. Matches OpenAPI schema PermissionGrantRequest (required: subject, permission, resource). Subject and Resource are combined typed strings ("user:alice", "doc:123").

NOTE: this is the ZANZIBAR grant shape. The account/RBAC grant/revoke (/permissions/{grant,revoke}) take query parameters, not this body — see GrantPermission/RevokePermission in roles.go.

type PermissionValidationRequest 

type PermissionValidationRequest struct {
	Permissions []string `json:"permissions"`
}

PermissionValidationRequest is the body for POST /permissions/registry/validate.

type PermissionValidationResponse 

type PermissionValidationResponse struct {
	Valid    bool            `json:"valid"`
	Results  map[string]bool `json:"results,omitempty"`
	Invalid  []string        `json:"invalid,omitempty"`
	Action   string          `json:"action,omitempty"`
	Reason   string          `json:"reason,omitempty"`
	Resource string          `json:"resource,omitempty"`
	Service  string          `json:"service,omitempty"`
	Type     string          `json:"type,omitempty"`
}

PermissionValidationResponse is the result of validating permission strings.

type PermissionsVisualizationResponse 

type PermissionsVisualizationResponse struct {
	UserID            string           `json:"user_id"`
	DirectPermissions []map[string]any `json:"direct_permissions,omitempty"`
	InheritedFrom     []map[string]any `json:"inherited_from,omitempty"`
}

PermissionsVisualizationResponse is a user's permission graph. Matches OpenAPI schema PermissionsVisualizationResponse (required: user_id).

type PolicyEvaluationResult 

type PolicyEvaluationResult struct {
	Allowed   bool   `json:"allowed"`
	IP        string `json:"ip,omitempty"`
	MatchedID string `json:"matched_policy_id,omitempty"`
	Reason    string `json:"reason,omitempty"`
}

PolicyEvaluationResult is the result of GET /network-policy/evaluate.

type Provider 

type Provider struct {
	ID           string          `json:"id"`
	Name         string          `json:"name,omitempty"`
	Type         string          `json:"type,omitempty"`
	Enabled      bool            `json:"enabled,omitempty"`
	Priority     int             `json:"priority,omitempty"`
	Domain       string          `json:"domain,omitempty"`
	IssuerURL    string          `json:"issuer_url,omitempty"`
	Config       map[string]any  `json:"config,omitempty"`
	CreatedAt    string          `json:"created_at,omitempty"`
	Description  string          `json:"description,omitempty"`
	IsActive     bool            `json:"is_active,omitempty"`
	IsDefault    bool            `json:"is_default,omitempty"`
	Metadata     json.RawMessage `json:"metadata,omitempty"`
	OrgID        string          `json:"org_id,omitempty"`
	ProviderType string          `json:"provider_type,omitempty"`
	Status       string          `json:"status,omitempty"`
	UpdatedAt    string          `json:"updated_at,omitempty"`
}

Provider is a provider configuration record (response shape is permissive).

type ProviderConfigCreate 

type ProviderConfigCreate struct {
	Name         string         `json:"name"`
	Type         string         `json:"type"` // e.g. "oidc", "saml", "google", "okta"
	Enabled      bool           `json:"enabled,omitempty"`
	Priority     int            `json:"priority,omitempty"`
	ClientID     string         `json:"client_id,omitempty"`
	ClientSecret string         `json:"client_secret,omitempty"`
	IssuerURL    string         `json:"issuer_url,omitempty"`
	Domain       string         `json:"domain,omitempty"`
	Config       map[string]any `json:"config,omitempty"`
}

ProviderConfigCreate is the body for POST /providers/.

type ProviderConfigUpdate 

type ProviderConfigUpdate struct {
	Name         *string         `json:"name,omitempty"`
	Enabled      *bool           `json:"enabled,omitempty"`
	Priority     *int            `json:"priority,omitempty"`
	ClientID     *string         `json:"client_id,omitempty"`
	ClientSecret *string         `json:"client_secret,omitempty"`
	IssuerURL    *string         `json:"issuer_url,omitempty"`
	Domain       *string         `json:"domain,omitempty"`
	Config       *map[string]any `json:"config,omitempty"`
}

ProviderConfigUpdate is the body for PUT /providers/{provider_id}.

type ProviderStatusUpdateRequest 

type ProviderStatusUpdateRequest struct {
	ProviderID string `json:"provider_id"`
	Enabled    bool   `json:"enabled"`
	Reason     string `json:"reason,omitempty"`
}

ProviderStatusUpdateRequest is the body for POST /admin/providers/status.

type ProviderStatusUpdateResponse 

type ProviderStatusUpdateResponse struct {
	ProviderID     string `json:"provider_id,omitempty"`
	Enabled        bool   `json:"enabled,omitempty"`
	Message        string `json:"message,omitempty"`
	NewStatus      string `json:"new_status,omitempty"`
	PreviousStatus string `json:"previous_status,omitempty"`
	Reason         string `json:"reason,omitempty"`
	StatusUpdated  bool   `json:"status_updated,omitempty"`
	UpdatedAt      string `json:"updated_at,omitempty"`
}

ProviderStatusUpdateResponse is the result of updating provider status.

type ProviderTestRequest 

type ProviderTestRequest struct {
	ProviderID string         `json:"provider_id,omitempty"`
	Type       string         `json:"type,omitempty"`
	Config     map[string]any `json:"config,omitempty"`
}

ProviderTestRequest is the body for POST /providers/test.

type ProviderTestResponse 

type ProviderTestResponse struct {
	Success        bool            `json:"success"`
	Message        string          `json:"message,omitempty"`
	Details        map[string]any  `json:"details,omitempty"`
	Error          string          `json:"error,omitempty"`
	Metadata       json.RawMessage `json:"metadata,omitempty"`
	ResponseTimeMs float64         `json:"response_time_ms,omitempty"`
}

ProviderTestResponse is the result of a provider connectivity test.

type PublicLoginConfig 

type PublicLoginConfig struct {
	OrgSlug           string            `json:"org_slug,omitempty"`
	OrgName           string            `json:"org_name,omitempty"`
	LogoURL           string            `json:"logo_url,omitempty"`
	PrimaryColor      string            `json:"primary_color,omitempty"`
	BackgroundColor   string            `json:"background_color,omitempty"`
	AllowPassword     bool              `json:"allow_password,omitempty"`
	AllowSignup       bool              `json:"allow_signup,omitempty"`
	AllowPasswordless bool              `json:"allow_passwordless,omitempty"`
	Providers         []OrgProviderInfo `json:"providers,omitempty"`
}

PublicLoginConfig is the public subset of a tenant's login config.

type PushedAuthorizationResponse 

type PushedAuthorizationResponse struct {
	RequestURI string `json:"request_uri"`
	ExpiresIn  int    `json:"expires_in,omitempty"`
}

PushedAuthorizationResponse is the RFC 9126 PAR result.

type QuotaCheckResponse 

type QuotaCheckResponse struct {
	ResourceType string `json:"resource_type,omitempty"`
	Allowed      bool   `json:"allowed"`
	Used         int64  `json:"used,omitempty"`
	Limit        int64  `json:"limit,omitempty"`
	Remaining    int64  `json:"remaining,omitempty"`
	CurrentUsage int64  `json:"current_usage,omitempty"`
	Message      string `json:"message,omitempty"`
	Tier         string `json:"tier,omitempty"`
}

QuotaCheckResponse is the result of GET /quotas/check/{resource_type}.

type QuotaTier 

type QuotaTier struct {
	Name   string           `json:"name"`
	Limits map[string]int64 `json:"limits,omitempty"`
	Price  string           `json:"price,omitempty"`
}

QuotaTier describes one subscription tier.

type QuotaTierLimits added in v0.10.0 

type QuotaTierLimits struct {
	MaxOrganizationsPerUser int64 `json:"max_organizations_per_user,omitempty"`
	MaxUsersPerOrg          int64 `json:"max_users_per_org,omitempty"`
	MaxTeamsPerOrg          int64 `json:"max_teams_per_org,omitempty"`
	MaxAPIKeysPerOrg        int64 `json:"max_api_keys_per_org,omitempty"`
	MaxPermissionsPerUser   int64 `json:"max_permissions_per_user,omitempty"`
	MaxDelegationsPerUser   int64 `json:"max_delegations_per_user,omitempty"`
	StorageQuotaMB          int64 `json:"storage_quota_mb,omitempty"`
	APIRateLimitPerHour     int64 `json:"api_rate_limit_per_hour,omitempty"`
}

QuotaTierLimits is the per-tier limit set the server returns as the value of each entry in QuotaTiersResponse.Tiers.

type QuotaTiersResponse 

type QuotaTiersResponse struct {
	Tiers      map[string]QuotaTierLimits `json:"tiers,omitempty"`
	UpgradeURL string                     `json:"upgrade_url,omitempty"`
}

QuotaTiersResponse is the result of GET /quotas/tiers. `tiers` is an object keyed by tier name (not an array); an earlier revision modeled it as a slice, so the real object body failed to decode entirely.

type QuotaUsageItem deprecated 

type QuotaUsageItem struct {
	ResourceType string  `json:"resource_type"`
	Used         int64   `json:"used"`
	Limit        int64   `json:"limit"`
	Remaining    int64   `json:"remaining,omitempty"`
	Percent      float64 `json:"percent,omitempty"`
}

QuotaUsageItem is usage for one resource type.

Deprecated: /quotas/my-usage does not return an array of these. The server returns object maps keyed by resource type (see QuotaUsageResponse). Retained for source compatibility; no endpoint decodes into it.

type QuotaUsageResponse 

type QuotaUsageResponse struct {
	UserID string `json:"user_id,omitempty"`
	Tier   string `json:"tier,omitempty"`
	// Usage/Limits/Percentages are keyed by resource type.
	Usage       map[string]int64   `json:"usage,omitempty"`
	Limits      map[string]int64   `json:"limits,omitempty"`
	Percentages map[string]float64 `json:"percentages,omitempty"`
}

QuotaUsageResponse is the result of GET /quotas/my-usage. The server returns object MAPS keyed by resource type (not arrays); an earlier revision modeled `usage` as a slice, so the real object body failed to decode entirely.

type RecentAlertsResponse 

type RecentAlertsResponse struct {
	Alerts          []AlertEntry    `json:"alerts"`
	TimeRange       json.RawMessage `json:"time_range,omitempty"`
	TotalCount      int64           `json:"total_count,omitempty"`
	UnresolvedCount int64           `json:"unresolved_count,omitempty"`
}

RecentAlertsResponse lists recent alerts.

type RecoveryCodesResponse 

type RecoveryCodesResponse struct {
	Codes         []string `json:"codes"`
	Generated     int      `json:"generated,omitempty"`
	Message       string   `json:"message,omitempty"`
	RecoveryCodes []string `json:"recovery_codes,omitempty"`
}

RecoveryCodesResponse is the result of generating MFA recovery codes.

type RefreshRequest 

type RefreshRequest struct {
	RefreshToken string `json:"refresh_token"`
}

RefreshRequest is the body for POST /auth/refresh.

type RegisterRequest 

type RegisterRequest struct {
	Email        string `json:"email"`
	Password     string `json:"password"`
	Name         string `json:"name,omitempty"`
	OrgID        string `json:"org_id,omitempty"`
	ProviderType string `json:"provider_type,omitempty"`
}

RegisterRequest is the body for POST /auth/register.

type RegisteredService 

type RegisteredService struct {
	Service     string   `json:"service"`
	Permissions []string `json:"permissions,omitempty"`
	Description string   `json:"description,omitempty"`
}

RegisteredService describes a service that has registered permissions.

type RegisteredServicesResponse 

type RegisteredServicesResponse struct {
	Services []RegisteredService `json:"services"`
	Total    int                 `json:"total,omitempty"`
}

RegisteredServicesResponse is the result of GET /permissions/registry/services.

type RegistryStatsResponse 

type RegistryStatsResponse struct {
	TotalServices    int      `json:"total_services,omitempty"`
	TotalPermissions int      `json:"total_permissions,omitempty"`
	ServicesList     []string `json:"services_list,omitempty"`
}

RegistryStatsResponse is the result of GET /permissions/registry/stats.

type RelationshipEntry 

type RelationshipEntry struct {
	Relation  string         `json:"relation"`
	Subject   string         `json:"subject"`
	Context   map[string]any `json:"context,omitempty"`
	CreatedAt string         `json:"created_at,omitempty"`
	ExpiresAt string         `json:"expires_at,omitempty"`
}

RelationshipEntry is a stored relationship tuple as returned by reads. Matches OpenAPI schema RelationshipEntry (required: relation, subject). CreatedAt/ExpiresAt are left as raw strings because the server's OpenAPI types them as anyOf[str, date-time, null] — a plain string is a valid value.

type RelationshipRequest 

type RelationshipRequest struct {
	Object    string         `json:"object"`
	Relation  string         `json:"relation"`
	Subject   string         `json:"subject"`
	Context   map[string]any `json:"context,omitempty"`
	ExpiresAt *time.Time     `json:"expires_at,omitempty"`
}

RelationshipRequest is a SINGLE relationship tuple: object#relation@subject. Body for POST/DELETE /zanzibar/stores/{store_id}/relationships.

Matches OpenAPI schema RelationshipRequest (required: object, relation, subject). Object/Subject are combined typed strings ("doc:123", "user:alice"); build them with Object()/Subject().

type RelationshipsPage 

type RelationshipsPage struct {
	Object            string              `json:"object"`
	Relationships     []RelationshipEntry `json:"relationships,omitempty"`
	ContinuationToken string              `json:"continuation_token,omitempty"`
}

RelationshipsPage is the (nominally cursored) form of RelationshipsResponse.

SERVER-GAP (pagination): the auth service does NOT paginate list-relationships (see ListRelationshipsPaged). ContinuationToken is forward-looking and always comes back empty from the current server. It matches RelationshipsResponse on the wire: {object, relationships:[]RelationshipEntry}.

type RelationshipsResponse 

type RelationshipsResponse struct {
	Object        string              `json:"object"`
	Relationships []RelationshipEntry `json:"relationships,omitempty"`
}

RelationshipsResponse lists the tuples for an object. Matches OpenAPI schema RelationshipsResponse (required: object).

type RequestInfo added in v0.5.0 

type RequestInfo struct {
	// Method is the HTTP method, e.g. "POST".
	Method string
	// Endpoint is the request path with any query string stripped — a stable,
	// low-cardinality label suitable as a metric dimension. Path parameters are
	// NOT templated, so ids do appear here; aggregate accordingly.
	Endpoint string
	// Status is the HTTP status code, or 0 when the request never got a response
	// (connection failure, timeout, cancelled context — Err says which).
	Status int
	// Duration is how long this attempt took.
	Duration time.Duration
	// Attempt is 0 for the first try, 1 for the first retry, and so on.
	Attempt int
	// Retrying reports whether the client is about to retry after this attempt.
	// Exactly one RequestInfo per logical call has Retrying == false.
	Retrying bool
	// Err is the transport error, if any. A non-2xx response is NOT an error
	// here — check Status. This field means the request did not complete.
	Err error
	// RequestID is the service's correlation id from the response, when present.
	// Quote it in a bug report; it is how the service finds your call in its logs.
	RequestID string
}

RequestInfo describes one completed HTTP attempt. A call that is retried produces one RequestInfo per attempt, so retry behaviour is visible rather than hidden inside a single "slow call".

type Resource 

type Resource struct {
	Type string
	ID   string
}

Resource is an optional fine-grained target for a permission decision. Zero value means "no specific resource".

func (Resource) IsZero 

func (r Resource) IsZero() bool

IsZero reports whether no resource was specified.

type RetryPolicy added in v0.10.0 

type RetryPolicy struct {
	MaxAttempts         int     `json:"max_attempts,omitempty"`
	InitialDelaySeconds int     `json:"initial_delay_seconds,omitempty"`
	MaxDelaySeconds     int     `json:"max_delay_seconds,omitempty"`
	BackoffMultiplier   float64 `json:"backoff_multiplier,omitempty"`
	Jitter              bool    `json:"jitter,omitempty"`
}

RetryPolicy configures webhook delivery retries.

type RevocationAuditEntry 

type RevocationAuditEntry struct {
	ID        string `json:"id,omitempty"`
	Type      string `json:"type,omitempty"`
	Subject   string `json:"subject,omitempty"`
	Actor     string `json:"actor,omitempty"`
	Reason    string `json:"reason,omitempty"`
	Timestamp string `json:"timestamp,omitempty"`
}

RevocationAuditEntry is one entry from GET /admin/audit/revocations.

type RevokeResult 

type RevokeResult struct {
	Revoked bool   `json:"revoked,omitempty"`
	Message string `json:"message,omitempty"`
}

RevokeResult is the response from POST /auth/revoke and /token/revoke. Per RFC 7009 the revocation endpoint may return an empty body; in that case Revoked defaults to false but a nil error indicates success.

type RevokedKeysListResponse 

type RevokedKeysListResponse struct {
	RevokedKeys []map[string]any `json:"revoked_keys"`
	Total       int              `json:"total,omitempty"`
	Count       int64            `json:"count,omitempty"`
	RetrievedAt string           `json:"retrieved_at,omitempty"`
}

RevokedKeysListResponse is the result of GET /admin/jwks/revoked.

type RoleDefinition 

type RoleDefinition struct {
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
}

RoleDefinition describes a role and the permissions it grants.

type RoleUpdateResponse 

type RoleUpdateResponse struct {
	Message string `json:"message,omitempty"`
	UserID  string `json:"user_id,omitempty"`
	Role    string `json:"role,omitempty"`
}

RoleUpdateResponse is the result of changing a member's role.

type RolesResponse 

type RolesResponse struct {
	Roles map[string]RoleDefinition `json:"roles"`
}

RolesResponse is the result of GET /permissions/roles (map keyed by role name).

type RotationStatusResponse 

type RotationStatusResponse struct {
	Rotating               bool            `json:"rotating,omitempty"`
	CurrentKid             string          `json:"current_kid,omitempty"`
	LastRotated            string          `json:"last_rotated,omitempty"`
	Configuration          json.RawMessage `json:"configuration,omitempty"`
	KeyInventory           json.RawMessage `json:"key_inventory,omitempty"`
	RotationCheck          json.RawMessage `json:"rotation_check,omitempty"`
	RotationServiceHealthy bool            `json:"rotation_service_healthy,omitempty"`
	StatusTimestamp        string          `json:"status_timestamp,omitempty"`
	Warnings               []string        `json:"warnings,omitempty"`
}

RotationStatusResponse is the result of GET /admin/jwks/rotation-status.

type SAMLAnalyticsResponse 

type SAMLAnalyticsResponse struct {
	TotalLogins             int            `json:"total_logins,omitempty"`
	ActiveSessions          int            `json:"active_sessions,omitempty"`
	Stats                   map[string]any `json:"stats,omitempty"`
	AuthenticationsThisWeek int64          `json:"authentications_this_week,omitempty"`
	AuthenticationsToday    int64          `json:"authentications_today,omitempty"`
	RecentActivity          []string       `json:"recent_activity,omitempty"`
	TopServiceProviders     []string       `json:"top_service_providers,omitempty"`
	TotalSps                int64          `json:"total_sps,omitempty"`
}

SAMLAnalyticsResponse reports SAML usage analytics.

type SAMLAssertionResult 

type SAMLAssertionResult struct {
	AccessToken  string         `json:"access_token,omitempty"`
	RefreshToken string         `json:"refresh_token,omitempty"`
	NameID       string         `json:"name_id,omitempty"`
	SessionIndex string         `json:"session_index,omitempty"`
	Attributes   map[string]any `json:"attributes,omitempty"`
	RelayState   string         `json:"relay_state,omitempty"`
}

SAMLAssertionResult is the result of the assertion-consumer service.

type SAMLAttributeMappingResponse 

type SAMLAttributeMappingResponse struct {
	Mappings map[string]string `json:"mappings"`
	Format   string            `json:"format,omitempty"`
}

SAMLAttributeMappingResponse is the SAML attribute-mapping configuration.

type SAMLAttributeMappingUpdate 

type SAMLAttributeMappingUpdate struct {
	Mappings map[string]string `json:"mappings"`
}

SAMLAttributeMappingUpdate is the body for PUT /saml/attributes/mappings.

type SAMLCertificate 

type SAMLCertificate struct {
	Use         string `json:"use,omitempty"`
	Fingerprint string `json:"fingerprint,omitempty"`
	NotBefore   string `json:"not_before,omitempty"`
	NotAfter    string `json:"not_after,omitempty"`
	Active      bool   `json:"active,omitempty"`
}

SAMLCertificate describes a signing/encryption certificate.

type SAMLCertificateGenerateResponse 

type SAMLCertificateGenerateResponse struct {
	Certificate   string `json:"certificate,omitempty"`
	Fingerprint   string `json:"fingerprint,omitempty"`
	Message       string `json:"message,omitempty"`
	CertificateID string `json:"certificate_id,omitempty"`
	ExpiresAt     string `json:"expires_at,omitempty"`
}

SAMLCertificateGenerateResponse is the result of generating a certificate.

type SAMLCertificateStatusResponse 

type SAMLCertificateStatusResponse struct {
	Certificates      []SAMLCertificate `json:"certificates"`
	CertificateStatus json.RawMessage   `json:"certificate_status,omitempty"`
	SigningEnabled    bool              `json:"signing_enabled,omitempty"`
}

SAMLCertificateStatusResponse reports certificate status.

type SAMLLogoutResult 

type SAMLLogoutResult struct {
	Success     bool   `json:"success,omitempty"`
	RedirectURL string `json:"redirect_url,omitempty"`
	Message     string `json:"message,omitempty"`
}

SAMLLogoutResult is the result of a SAML single-logout.

type SAMLSPDetailResponse 

type SAMLSPDetailResponse struct {
	ServiceProvider             SAMLServiceProvider `json:"service_provider"`
	AllowedBindings             []string            `json:"allowed_bindings,omitempty"`
	AssertionConsumerServiceURL string              `json:"assertion_consumer_service_url,omitempty"`
	AttributeMapping            map[string]string   `json:"attribute_mapping,omitempty"`
	AttributesMapping           map[string]string   `json:"attributes_mapping,omitempty"`
	Certificate                 string              `json:"certificate,omitempty"`
	CreatedAt                   string              `json:"created_at,omitempty"`
	Description                 string              `json:"description,omitempty"`
	EntityID                    string              `json:"entity_id,omitempty"`
	IdPEntityID                 string              `json:"idp_entity_id,omitempty"`
	IdPSloURL                   string              `json:"idp_slo_url,omitempty"`
	MetadataURL                 string              `json:"metadata_url,omitempty"`
	Name                        string              `json:"name,omitempty"`
	NameIDFormat                string              `json:"name_id_format,omitempty"`
	OrgID                       string              `json:"org_id,omitempty"`
	SingleLogoutServiceURL      string              `json:"single_logout_service_url,omitempty"`
	Status                      string              `json:"status,omitempty"`
	UpdatedAt                   string              `json:"updated_at,omitempty"`
	WantAssertionsEncrypted     bool                `json:"want_assertions_encrypted,omitempty"`
	WantAssertionsSigned        bool                `json:"want_assertions_signed,omitempty"`
	X509Cert                    string              `json:"x509_cert,omitempty"`
}

SAMLSPDetailResponse wraps a service-provider detail.

type SAMLSPListResponse 

type SAMLSPListResponse struct {
	ServiceProviders []SAMLServiceProvider `json:"service_providers"`
	Total            int                   `json:"total,omitempty"`
	Count            int64                 `json:"count,omitempty"`
}

SAMLSPListResponse lists registered service providers.

type SAMLSPRegistrationResponse 

type SAMLSPRegistrationResponse struct {
	SPID               string   `json:"sp_id"`
	EntityID           string   `json:"entity_id,omitempty"`
	MetadataURL        string   `json:"metadata_url,omitempty"`
	Message            string   `json:"message,omitempty"`
	ComplianceFindings []string `json:"compliance_findings,omitempty"`
}

SAMLSPRegistrationResponse is the result of registering a service provider.

type SAMLSPUpdateResponse 

type SAMLSPUpdateResponse struct {
	SPID     string `json:"sp_id,omitempty"`
	Message  string `json:"message,omitempty"`
	Success  bool   `json:"success,omitempty"`
	EntityID string `json:"entity_id,omitempty"`
}

SAMLSPUpdateResponse is the result of updating a service provider.

type SAMLServiceProvider 

type SAMLServiceProvider struct {
	SPID         string `json:"sp_id"`
	EntityID     string `json:"entity_id,omitempty"`
	Name         string `json:"name,omitempty"`
	ACSURL       string `json:"acs_url,omitempty"`
	SLOURL       string `json:"slo_url,omitempty"`
	NameIDFormat string `json:"name_id_format,omitempty"`
	Status       string `json:"status,omitempty"`
	CreatedAt    string `json:"created_at,omitempty"`
}

SAMLServiceProvider is a registered service provider (detail view).

type SAMLServiceProviderConfig 

type SAMLServiceProviderConfig struct {
	EntityID             string            `json:"entity_id"`
	Name                 string            `json:"name,omitempty"`
	ACSURL               string            `json:"acs_url,omitempty"`
	SLOURL               string            `json:"slo_url,omitempty"`
	MetadataURL          string            `json:"metadata_url,omitempty"`
	MetadataXML          string            `json:"metadata_xml,omitempty"`
	NameIDFormat         string            `json:"name_id_format,omitempty"`
	WantAssertionsSigned bool              `json:"want_assertions_signed,omitempty"`
	SignAuthnRequests    bool              `json:"sign_authn_requests,omitempty"`
	AllowedRedirectURLs  []string          `json:"allowed_redirect_urls,omitempty"`
	AttributeMapping     map[string]string `json:"attribute_mapping,omitempty"`
}

SAMLServiceProviderConfig is the body for POST /saml/sp/register and the shape used to update a service provider.

type SAMLSession 

type SAMLSession struct {
	SessionIndex string `json:"session_index,omitempty"`
	NameID       string `json:"name_id,omitempty"`
	SPEntityID   string `json:"sp_entity_id,omitempty"`
	CreatedAt    string `json:"created_at,omitempty"`
}

SAMLSession is one active SAML session.

type SAMLSessionListResponse 

type SAMLSessionListResponse struct {
	Sessions []SAMLSession `json:"sessions"`
	Count    int64         `json:"count,omitempty"`
}

SAMLSessionListResponse lists active SAML sessions.

type SCIMConnection added in v0.10.0 

type SCIMConnection struct {
	OrgID       string `json:"org_id"`
	Configured  bool   `json:"configured"`
	Active      bool   `json:"active"`
	SCIMBaseURL string `json:"scim_base_url"`
	Token       string `json:"token,omitempty"`
	CreatedAt   string `json:"created_at,omitempty"`
	RotatedAt   string `json:"rotated_at,omitempty"`
}

SCIMConnection is an org's SCIM provisioning connection (the endpoint a SCIM client provisions against, plus its bearer token).

type SSOConfigResponse 

type SSOConfigResponse struct {
	Enabled            bool           `json:"enabled,omitempty"`
	Config             map[string]any `json:"config,omitempty"`
	AllowedDomains     []string       `json:"allowed_domains,omitempty"`
	CookieDomain       string         `json:"cookie_domain,omitempty"`
	MaxSessionDuration int64          `json:"max_session_duration,omitempty"`
	RequireMFA         bool           `json:"require_mfa,omitempty"`
	SessionTimeout     int64          `json:"session_timeout,omitempty"`
}

SSOConfigResponse is the result of GET /federation/sso/config.

type SSOConfigUpdateResponse 

type SSOConfigUpdateResponse struct {
	Message string         `json:"message,omitempty"`
	Config  map[string]any `json:"config,omitempty"`
}

SSOConfigUpdateResponse is the result of PUT /federation/sso/config.

type SSODomainConfigRequest 

type SSODomainConfigRequest struct {
	ProviderID string         `json:"provider_id,omitempty"`
	Enabled    bool           `json:"enabled,omitempty"`
	Config     map[string]any `json:"config,omitempty"`
}

SSODomainConfigRequest is the body for POST/PUT /federation/sso/domains/{domain}.

type SSODomainConfigResponse 

type SSODomainConfigResponse struct {
	Domain              string          `json:"domain"`
	ProviderID          string          `json:"provider_id,omitempty"`
	Enabled             bool            `json:"enabled,omitempty"`
	Config              map[string]any  `json:"config,omitempty"`
	Active              bool            `json:"active,omitempty"`
	AllowedAuthMethods  []string        `json:"allowed_auth_methods,omitempty"`
	AllowedRedirectUrls []string        `json:"allowed_redirect_urls,omitempty"`
	CreatedAt           string          `json:"created_at,omitempty"`
	DisplayName         string          `json:"display_name,omitempty"`
	EntityID            string          `json:"entity_id,omitempty"`
	ExpiresAt           string          `json:"expires_at,omitempty"`
	IPWhitelist         []string        `json:"ip_whitelist,omitempty"`
	LoginCallbackURL    string          `json:"login_callback_url,omitempty"`
	LogoutCallbackURL   string          `json:"logout_callback_url,omitempty"`
	Metadata            json.RawMessage `json:"metadata,omitempty"`
	RequireMFA          bool            `json:"require_mfa,omitempty"`
	SessionTimeout      int64           `json:"session_timeout,omitempty"`
	UpdatedAt           string          `json:"updated_at,omitempty"`
}

SSODomainConfigResponse is one domain's SSO configuration.

type SSODomainListResponse 

type SSODomainListResponse struct {
	Domains  []SSODomainConfigResponse `json:"domains"`
	Total    int                       `json:"total,omitempty"`
	Page     int64                     `json:"page,omitempty"`
	PageSize int64                     `json:"page_size,omitempty"`
}

SSODomainListResponse is the result of GET /federation/sso/domains.

type SSOPropagateResponse 

type SSOPropagateResponse struct {
	Success           bool     `json:"success,omitempty"`
	PropagatedTo      []string `json:"propagated_to,omitempty"`
	Message           string   `json:"message,omitempty"`
	PropagatedDomains []string `json:"propagated_domains,omitempty"`
	SessionID         string   `json:"session_id,omitempty"`
	Status            string   `json:"status,omitempty"`
}

SSOPropagateResponse is the result of POST /federation/sso/propagate.

type SSOSession 

type SSOSession struct {
	ID        string `json:"id"`
	UserID    string `json:"user_id,omitempty"`
	Provider  string `json:"provider,omitempty"`
	Domain    string `json:"domain,omitempty"`
	CreatedAt string `json:"created_at,omitempty"`
	ExpiresAt string `json:"expires_at,omitempty"`
}

SSOSession is one federated SSO session.

type SSOSessionCreateResponse 

type SSOSessionCreateResponse struct {
	Session    SSOSession `json:"session"`
	SessionID  string     `json:"session_id,omitempty"`
	CreatedAt  string     `json:"created_at,omitempty"`
	Domains    []string   `json:"domains,omitempty"`
	ExpiresIn  int64      `json:"expires_in,omitempty"`
	RememberMe bool       `json:"remember_me,omitempty"`
}

SSOSessionCreateResponse is the result of POST /federation/sso/sessions.

type SSOSessionDetailResponse 

type SSOSessionDetailResponse struct {
	Session    SSOSession `json:"session"`
	Active     bool       `json:"active,omitempty"`
	CreatedAt  string     `json:"created_at,omitempty"`
	Domains    []string   `json:"domains,omitempty"`
	ExpiresAt  string     `json:"expires_at,omitempty"`
	RememberMe bool       `json:"remember_me,omitempty"`
	SessionID  string     `json:"session_id,omitempty"`
	UserID     string     `json:"user_id,omitempty"`
}

SSOSessionDetailResponse is the result of GET /federation/sso/sessions/{id}.

type SSOSessionListResponse 

type SSOSessionListResponse struct {
	Sessions []SSOSession `json:"sessions"`
	Total    int          `json:"total,omitempty"`
	Count    int64        `json:"count,omitempty"`
}

SSOSessionListResponse is the result of GET /federation/sso/sessions.

type ScimEmail added in v0.10.0 

type ScimEmail struct {
	Value   string `json:"value"`
	Type    string `json:"type,omitempty"`
	Primary bool   `json:"primary,omitempty"`
}

ScimEmail is one entry in a SCIM user's emails.

type ScimGroup added in v0.10.0 

type ScimGroup struct {
	Schemas     []string          `json:"schemas"`
	ID          string            `json:"id,omitempty"`
	ExternalID  string            `json:"externalId,omitempty"`
	DisplayName string            `json:"displayName"`
	Members     []ScimGroupMember `json:"members,omitempty"`
	Meta        *ScimMeta         `json:"meta,omitempty"`
}

ScimGroup is a SCIM 2.0 Group resource.

type ScimGroupMember added in v0.10.0 

type ScimGroupMember struct {
	Value   string `json:"value"`
	Display string `json:"display,omitempty"`
	Ref     string `json:"$ref,omitempty"`
}

ScimGroupMember is one member reference in a SCIM group.

type ScimListResponse added in v0.10.0 

type ScimListResponse struct {
	Schemas      []string        `json:"schemas"`
	TotalResults int             `json:"totalResults"`
	StartIndex   int             `json:"startIndex"`
	ItemsPerPage int             `json:"itemsPerPage"`
	Resources    json.RawMessage `json:"Resources"`
}

ScimListResponse is a SCIM ListResponse. Resources is left as raw JSON so the caller decodes it into the concrete resource type (ScimUser/ScimGroup/...).

type ScimMeta added in v0.10.0 

type ScimMeta struct {
	ResourceType string `json:"resourceType,omitempty"`
	Created      string `json:"created,omitempty"`
	LastModified string `json:"lastModified,omitempty"`
	Location     string `json:"location,omitempty"`
	Version      string `json:"version,omitempty"`
}

ScimMeta is the SCIM resource metadata block.

type ScimName added in v0.10.0 

type ScimName struct {
	Formatted  string `json:"formatted,omitempty"`
	FamilyName string `json:"familyName,omitempty"`
	GivenName  string `json:"givenName,omitempty"`
}

ScimName is the SCIM name sub-attribute.

type ScimPatchOperation added in v0.10.0 

type ScimPatchOperation struct {
	Op    string `json:"op"`
	Path  string `json:"path,omitempty"`
	Value any    `json:"value,omitempty"`
}

ScimPatchOperation is one operation in a SCIM PatchOp (op is add/remove/replace).

type ScimPatchRequest added in v0.10.0 

type ScimPatchRequest struct {
	Schemas    []string             `json:"schemas"`
	Operations []ScimPatchOperation `json:"Operations"`
}

ScimPatchRequest is a SCIM PatchOp body (urn:ietf:params:scim:api:messages:2.0:PatchOp).

type ScimUser added in v0.10.0 

type ScimUser struct {
	Schemas     []string    `json:"schemas"`
	ID          string      `json:"id,omitempty"`
	ExternalID  string      `json:"externalId,omitempty"`
	UserName    string      `json:"userName"`
	Active      bool        `json:"active"`
	DisplayName string      `json:"displayName,omitempty"`
	Name        *ScimName   `json:"name,omitempty"`
	Emails      []ScimEmail `json:"emails,omitempty"`
	Meta        *ScimMeta   `json:"meta,omitempty"`
}

ScimUser is a SCIM 2.0 User resource.

type SelfDeleteRequest 

type SelfDeleteRequest struct {
	ConfirmEmail string `json:"confirm_email"`
}

SelfDeleteRequest is the confirmation body for DELETE /users/me. Matches OpenAPI schema SelfDeleteRequest (required: confirm_email).

ConfirmEmail MUST exactly match the authenticated caller's own account email. It is the irreversible-action guard — the same "type your address to confirm" pattern a UI would use. A mismatch is rejected and NO state changes.

type SelfDeleteResponse 

type SelfDeleteResponse struct {
	Success bool   `json:"success,omitempty"`
	Message string `json:"message,omitempty"`
	UserID  string `json:"user_id,omitempty"`
	Detail  string `json:"detail,omitempty"`
}

SelfDeleteResponse is the result of DELETE /users/me.

The server's response body is not tightly specified, so the useful fields are modelled optimistically and Raw retains anything else. Treat a nil error as the authoritative signal that the deletion was accepted.

type ServiceAccountCreate 

type ServiceAccountCreate struct {
	Name        string   `json:"name"`
	OrgID       string   `json:"org_id,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
	Description string   `json:"description,omitempty"`
}

ServiceAccountCreate is the body for POST /admin/users/create-service-account.

type ServiceAccountResponse 

type ServiceAccountResponse struct {
	UserID      string   `json:"user_id,omitempty"`
	Name        string   `json:"name,omitempty"`
	APIKey      string   `json:"api_key,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
	Message     string   `json:"message,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	Email       string   `json:"email,omitempty"`
	ID          string   `json:"id,omitempty"`
}

ServiceAccountResponse is the result of creating a service account.

type ServiceDiscoveryResponse 

type ServiceDiscoveryResponse struct {
	Service          string          `json:"service,omitempty"`
	Version          string          `json:"version,omitempty"`
	Status           string          `json:"status,omitempty"`
	Description      string          `json:"description,omitempty"`
	DiscoveryVersion string          `json:"discovery_version,omitempty"`
	Discovery        json.RawMessage `json:"discovery,omitempty"`
	APIGroups        json.RawMessage `json:"api_groups,omitempty"`
	AuthMethods      json.RawMessage `json:"auth_methods,omitempty"`
	Capabilities     json.RawMessage `json:"capabilities,omitempty"`
	MeshNetwork      json.RawMessage `json:"mesh_network,omitempty"`
	Resources        json.RawMessage `json:"resources,omitempty"`
	StartHere        json.RawMessage `json:"start_here,omitempty"`
}

ServiceDiscoveryResponse is the result of GET / (root discovery). Nested objects are raw JSON so callers can decode the parts they need.

type ServicePermissionRegister 

type ServicePermissionRegister struct {
	Service     string   `json:"service"`
	Permissions []string `json:"permissions"`
	Description string   `json:"description,omitempty"`
}

ServicePermissionRegister is the body for POST /permissions/registry/register.

type ServicePermissionResponse 

type ServicePermissionResponse struct {
	Service      string   `json:"service,omitempty"`
	Permissions  []string `json:"permissions,omitempty"`
	Message      string   `json:"message,omitempty"`
	Actions      int64    `json:"actions,omitempty"`
	Reason       string   `json:"reason,omitempty"`
	RegisteredAt string   `json:"registered_at,omitempty"`
	Resources    int64    `json:"resources,omitempty"`
	Valid        bool     `json:"valid,omitempty"`
}

ServicePermissionResponse is the result of registering service permissions.

type ServiceStatusResponse 

type ServiceStatusResponse struct {
	Status            string            `json:"status"`
	Uptime            string            `json:"uptime,omitempty"`
	Details           map[string]any    `json:"details,omitempty"`
	Checks            map[string]string `json:"checks,omitempty"`
	CircuitBreakers   json.RawMessage   `json:"circuit_breakers,omitempty"`
	Configuration     json.RawMessage   `json:"configuration,omitempty"`
	Dependencies      map[string]string `json:"dependencies,omitempty"`
	Enterprise        json.RawMessage   `json:"enterprise,omitempty"`
	Features          json.RawMessage   `json:"features,omitempty"`
	Metrics           json.RawMessage   `json:"metrics,omitempty"`
	Oauth21           json.RawMessage   `json:"oauth21,omitempty"`
	PasswordPolicy    json.RawMessage   `json:"password_policy,omitempty"`
	Runtime           string            `json:"runtime,omitempty"`
	Service           string            `json:"service,omitempty"`
	Timestamp         float64           `json:"timestamp,omitempty"`
	UptimeSec         int64             `json:"uptime_sec,omitempty"`
	Version           string            `json:"version,omitempty"`
	ZanzibarMigration json.RawMessage   `json:"zanzibar_migration,omitempty"`
}

ServiceStatusResponse is the result of GET /status.

type SessionRevokeResponse 

type SessionRevokeResponse struct {
	Message      string `json:"message,omitempty"`
	RevokedCount int    `json:"revoked_count,omitempty"`
}

SessionRevokeResponse is the result of revoking a user's sessions.

type SuperAdminActiveGrantsResponse 

type SuperAdminActiveGrantsResponse struct {
	Grants       []map[string]any `json:"grants"`
	Total        int              `json:"total,omitempty"`
	ActiveGrants json.RawMessage  `json:"active_grants,omitempty"`
	Count        int64            `json:"count,omitempty"`
	RetrievedAt  string           `json:"retrieved_at,omitempty"`
}

SuperAdminActiveGrantsResponse is the result of GET /super-admin/active-grants.

type SuperAdminCleanupResponse 

type SuperAdminCleanupResponse struct {
	CleanedCount int    `json:"cleaned_count,omitempty"`
	Message      string `json:"message,omitempty"`
	CleanupTime  string `json:"cleanup_time,omitempty"`
	ExpiredCount int64  `json:"expired_count,omitempty"`
	Success      bool   `json:"success,omitempty"`
}

SuperAdminCleanupResponse is the result of POST /super-admin/cleanup-expired.

type SuperAdminExtendRequestModel 

type SuperAdminExtendRequestModel struct {
	GrantID           string `json:"grant_id"`
	AdditionalSeconds int    `json:"additional_seconds,omitempty"`
	Reason            string `json:"reason,omitempty"`
}

SuperAdminExtendRequestModel is the body for POST /super-admin/extend.

type SuperAdminExtendResponse 

type SuperAdminExtendResponse struct {
	GrantID   string `json:"grant_id,omitempty"`
	ExpiresAt string `json:"expires_at,omitempty"`
	Message   string `json:"message,omitempty"`
	Status    string `json:"status,omitempty"`
	Success   bool   `json:"success,omitempty"`
}

SuperAdminExtendResponse is the result of POST /super-admin/extend.

type SuperAdminGrantRequestModel 

type SuperAdminGrantRequestModel struct {
	UserID           string   `json:"user_id"`
	Permissions      []string `json:"permissions"`
	DurationSeconds  int      `json:"duration_seconds,omitempty"`
	Reason           string   `json:"reason,omitempty"`
	RequiresApproval bool     `json:"requires_approval,omitempty"`
}

SuperAdminGrantRequestModel is the body for POST /super-admin/grant.

type SuperAdminGrantResponse 

type SuperAdminGrantResponse struct {
	GrantID      string `json:"grant_id,omitempty"`
	UserID       string `json:"user_id,omitempty"`
	Status       string `json:"status,omitempty"`
	ExpiresAt    string `json:"expires_at,omitempty"`
	Message      string `json:"message,omitempty"`
	ApprovalID   string `json:"approval_id,omitempty"`
	Instructions string `json:"instructions,omitempty"`
	SessionID    string `json:"session_id,omitempty"`
	Success      bool   `json:"success,omitempty"`
}

SuperAdminGrantResponse is the result of POST /super-admin/grant.

type SuperAdminRevokeRequestModel 

type SuperAdminRevokeRequestModel struct {
	GrantID string `json:"grant_id,omitempty"`
	UserID  string `json:"user_id,omitempty"`
	Reason  string `json:"reason,omitempty"`
}

SuperAdminRevokeRequestModel is the body for POST /super-admin/revoke.

type SuperAdminRevokeResponse 

type SuperAdminRevokeResponse struct {
	GrantID   string `json:"grant_id,omitempty"`
	Revoked   bool   `json:"revoked,omitempty"`
	Message   string `json:"message,omitempty"`
	RevokedAt string `json:"revoked_at,omitempty"`
	Success   bool   `json:"success,omitempty"`
}

SuperAdminRevokeResponse is the result of POST /super-admin/revoke.

type SwitchOrganizationRequest 

type SwitchOrganizationRequest struct {
	OrgID string `json:"org_id"`
}

SwitchOrganizationRequest is the body for POST /auth/switch-organization.

type Team 

type Team struct {
	ID           string          `json:"id"`
	OrgID        string          `json:"org_id,omitempty"`
	Name         string          `json:"name"`
	Slug         string          `json:"slug,omitempty"`
	Description  string          `json:"description,omitempty"`
	ParentID     string          `json:"parent_id,omitempty"`
	MemberCount  int             `json:"member_count,omitempty"`
	Metadata     map[string]any  `json:"metadata,omitempty"`
	CreatedAt    string          `json:"created_at,omitempty"`
	ParentTeamID string          `json:"parent_team_id,omitempty"`
	Permissions  []string        `json:"permissions,omitempty"`
	Settings     json.RawMessage `json:"settings,omitempty"`
	UpdatedAt    string          `json:"updated_at,omitempty"`
}

Team is a team/group within an organization.

type TeamCreate 

type TeamCreate struct {
	Name        string         `json:"name"`
	Slug        string         `json:"slug,omitempty"`
	Description string         `json:"description,omitempty"`
	ParentID    string         `json:"parent_id,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

TeamCreate is the body for POST /organizations/{org_id}/teams.

type TeamMember 

type TeamMember struct {
	UserID  string `json:"user_id"`
	Email   string `json:"email,omitempty"`
	Name    string `json:"name,omitempty"`
	Role    string `json:"role,omitempty"`
	AddedAt string `json:"added_at,omitempty"`
}

TeamMember is one team member entry.

type TeamMemberAdd 

type TeamMemberAdd struct {
	UserID string `json:"user_id"`
	Role   string `json:"role,omitempty"`
}

TeamMemberAdd is the body for POST /teams/{team_id}/members.

type TeamMemberRoleUpdate 

type TeamMemberRoleUpdate struct {
	Role string `json:"role"`
}

TeamMemberRoleUpdate is the body for PUT /teams/{team_id}/members/{user_id}.

type TeamMembershipRequest 

type TeamMembershipRequest struct {
	UserID string `json:"user_id"`
	TeamID string `json:"team_id"`
	Role   string `json:"role,omitempty"`
}

TeamMembershipRequest is the body for POST /zanzibar/stores/{store_id}/teams/membership. Matches OpenAPI schema TeamMembershipRequest (required: user_id, team_id) — a SINGLE membership, not a batch.

type TeamPermissionsResponse 

type TeamPermissionsResponse struct {
	TeamID      string   `json:"team_id,omitempty"`
	Permissions []string `json:"permissions"`
}

TeamPermissionsResponse is the result of GET /teams/{team_id}/permissions.

type TeamUpdate 

type TeamUpdate struct {
	Name        *string         `json:"name,omitempty"`
	Description *string         `json:"description,omitempty"`
	Metadata    *map[string]any `json:"metadata,omitempty"`
}

TeamUpdate is the body for PUT /teams/{team_id}.

type TempAllowlistCreateResponse 

type TempAllowlistCreateResponse struct {
	EntryID   string `json:"entry_id"`
	ExpiresAt string `json:"expires_at,omitempty"`
	Message   string `json:"message,omitempty"`
	IPAddress string `json:"ip_address,omitempty"`
	Status    string `json:"status,omitempty"`
	UserID    string `json:"user_id,omitempty"`
}

TempAllowlistCreateResponse is the result of creating a temp allowlist entry.

type TempAllowlistEntry 

type TempAllowlistEntry struct {
	ID        string `json:"id"`
	IP        string `json:"ip,omitempty"`
	Reason    string `json:"reason,omitempty"`
	CreatedAt string `json:"created_at,omitempty"`
	ExpiresAt string `json:"expires_at,omitempty"`
}

TempAllowlistEntry is one temporary allowlist entry.

type TempAllowlistListResponse 

type TempAllowlistListResponse struct {
	Entries []TempAllowlistEntry `json:"entries"`
	Count   int64                `json:"count,omitempty"`
}

TempAllowlistListResponse lists temporary allowlist entries.

type TempAllowlistRequest 

type TempAllowlistRequest struct {
	IP         string `json:"ip"`
	Reason     string `json:"reason,omitempty"`
	TTLSeconds int    `json:"ttl_seconds,omitempty"`
}

TempAllowlistRequest is the body for POST /network-policy/temp-allowlist.

type TemplatePreviewResponse 

type TemplatePreviewResponse struct {
	Subject  string `json:"subject,omitempty"`
	HTMLBody string `json:"html_body,omitempty"`
	TextBody string `json:"text_body,omitempty"`
}

TemplatePreviewResponse is the rendered preview of an email template.

type TemplateTypeInfo 

type TemplateTypeInfo struct {
	Type        string   `json:"type"`
	Description string   `json:"description,omitempty"`
	Variables   []string `json:"variables,omitempty"`
}

TemplateTypeInfo describes one available email template type.

type TemplateTypesResponse 

type TemplateTypesResponse struct {
	TemplateTypes []TemplateTypeInfo `json:"template_types"`
}

TemplateTypesResponse lists available template types.

type TestEmailRequest 

type TestEmailRequest struct {
	To       string `json:"to"`
	Template string `json:"template,omitempty"`
}

TestEmailRequest is the body for POST /organizations/{org_id}/emails/test.

type TestEmailSentResponse 

type TestEmailSentResponse struct {
	Message string `json:"message,omitempty"`
	Success bool   `json:"success,omitempty"`
	EmailID string `json:"email_id,omitempty"`
}

TestEmailSentResponse is the result of sending a test email.

type TokenActorInfo added in v0.10.0 

type TokenActorInfo struct {
	ID    string `json:"id"`
	Email string `json:"email"`
	Name  string `json:"name,omitempty"`
}

TokenActorInfo identifies the principal acting on another user's behalf on a delegated token (the "actor" object the auth service embeds).

type TokenResponse 

type TokenResponse struct {
	AccessToken  string `json:"access_token,omitempty"`
	TokenType    string `json:"token_type,omitempty"`
	ExpiresIn    int    `json:"expires_in,omitempty"`
	RefreshToken string `json:"refresh_token,omitempty"`
	IDToken      string `json:"id_token,omitempty"`
	Scope        string `json:"scope,omitempty"`
}

TokenResponse is the OAuth2 token-endpoint response (POST /auth/oauth/token, /token/refresh, provider callbacks). It mirrors the standard token payload.

type TokenSet 

type TokenSet struct {
	AccessToken  string        `json:"access_token"`
	RefreshToken string        `json:"refresh_token"`
	TokenType    string        `json:"token_type,omitempty"` // "bearer"
	ExpiresIn    int           `json:"expires_in,omitempty"` // seconds
	User         TokenUserInfo `json:"user"`
	Audience     []string      `json:"audience,omitempty"`
	// Provider is the auth provider that issued the token (e.g. "internal",
	// "google"); Scope is the granted scope. Both are returned on TokenResponse
	// (Refresh / Delegate / SwitchOrganization).
	Provider string `json:"provider,omitempty"`
	Scope    string `json:"scope,omitempty"`
}

TokenSet is the result of Login / Refresh / SwitchOrganization (LoginResponse / TokenResponse in the API).

type TokenSource 

type TokenSource interface {
	Token(ctx context.Context) (string, error)
}

TokenSource supplies (and can refresh) a bearer token. A CLI/agent implements or uses this to carry credentials across calls.

type TokenUserInfo 

type TokenUserInfo struct {
	ID          string `json:"id"`
	Email       string `json:"email"`
	Name        string `json:"name,omitempty"`
	OrgID       string `json:"org_id,omitempty"`
	IsDelegated bool   `json:"is_delegated,omitempty"`
	// Actor identifies the principal acting on the user's behalf when this token
	// is delegated/impersonated. Nil for a direct (non-delegated) token.
	Actor *TokenActorInfo `json:"actor,omitempty"`
}

TokenUserInfo is the embedded user summary returned with a token set.

type TokenValidationRequest 

type TokenValidationRequest struct {
	Token               string   `json:"token"`
	RequiredPermissions []string `json:"required_permissions,omitempty"`
	ResourceType        string   `json:"resource_type,omitempty"`
	ResourceID          string   `json:"resource_id,omitempty"`
	ExpectedAudience    string   `json:"expected_audience,omitempty"`
	IncludePermissions  bool     `json:"include_permissions,omitempty"`
}

TokenValidationRequest is the body for POST /auth/validate-token.

type TransactRelationshipsRequest 

type TransactRelationshipsRequest struct {
	Writes  []RelationshipRequest `json:"writes,omitempty"`
	Deletes []RelationshipRequest `json:"deletes,omitempty"`
}

TransactRelationshipsRequest writes and deletes tuples in ONE atomic (all-or-nothing) transaction — e.g. re-parenting an object requires deleting the old edge and writing the new one together. Each write/delete is a single RelationshipRequest tuple (combined `object`/`subject` strings).

type UpdateNetworkPolicyRequest 

type UpdateNetworkPolicyRequest struct {
	Name                  *string   `json:"name,omitempty"`
	Description           *string   `json:"description,omitempty"`
	Priority              *int      `json:"priority,omitempty"`
	Enabled               *bool     `json:"enabled,omitempty"`
	Action                *string   `json:"action,omitempty"`
	Networks              *[]string `json:"networks,omitempty"`
	GeoCountries          *[]string `json:"geo_countries,omitempty"`
	GeoMode               *string   `json:"geo_mode,omitempty"`
	RestrictedPermissions *[]string `json:"restricted_permissions,omitempty"`
	RequireMFA            *bool     `json:"require_mfa,omitempty"`
	ExpiresAt             *string   `json:"expires_at,omitempty"`
}

UpdateNetworkPolicyRequest is the body for PUT /network-policy/{policy_id}.

type User 

type User struct {
	ID            string                 `json:"id"`
	Email         string                 `json:"email"`
	Name          string                 `json:"name,omitempty"`
	Status        string                 `json:"status,omitempty"`
	EmailVerified bool                   `json:"email_verified,omitempty"`
	Phone         string                 `json:"phone,omitempty"`
	AvatarURL     string                 `json:"avatar_url,omitempty"`
	Timezone      string                 `json:"timezone,omitempty"`
	Language      string                 `json:"language,omitempty"`
	ProviderType  string                 `json:"provider_type,omitempty"`
	OrgID         string                 `json:"org_id,omitempty"`        // UserResponse
	ActiveOrgID   string                 `json:"active_org_id,omitempty"` // UserProfile
	Organizations []UserOrganizationInfo `json:"organizations,omitempty"` // UserProfile
	Metadata      map[string]any         `json:"metadata,omitempty"`
	// CreatedAt/UpdatedAt/LastLogin are returned by the user read endpoints
	// (UserProfile / UserResponse). created_at is required on UserProfile.
	CreatedAt string   `json:"created_at,omitempty"`
	UpdatedAt string   `json:"updated_at,omitempty"`
	LastLogin string   `json:"last_login,omitempty"`
	Roles     []string `json:"roles,omitempty"`
}

User is the profile returned by GET /users/{user_id}, /users/me, /auth/me. Fields are a superset that tolerates both UserProfile and UserResponse.

type UserOrganizationInfo 

type UserOrganizationInfo struct {
	ID            string   `json:"id"`
	Name          string   `json:"name"`
	Type          string   `json:"type"`
	Role          string   `json:"role"`
	IsPersonal    bool     `json:"is_personal"`
	IsDefault     bool     `json:"is_default"`
	JoinedAt      string   `json:"joined_at,omitempty"`
	Permissions   []string `json:"permissions"`
	ParentID      string   `json:"parent_id,omitempty"`
	WorkspaceType string   `json:"workspace_type,omitempty"`
}

UserOrganizationInfo is one membership entry (GET /users/me/organizations).

type UserPermissions 

type UserPermissions struct {
	UserID      string   `json:"user_id"`
	OrgID       string   `json:"org_id,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
}

UserPermissions is the result of GET /permissions/user/{user_id}.

type UserUpdate 

type UserUpdate struct {
	Name      *string         `json:"name,omitempty"`
	Phone     *string         `json:"phone,omitempty"`
	AvatarURL *string         `json:"avatar_url,omitempty"`
	Timezone  *string         `json:"timezone,omitempty"`
	Language  *string         `json:"language,omitempty"`
	Metadata  *map[string]any `json:"metadata,omitempty"`
}

UserUpdate is the body for PUT /users/me and PUT /users/{user_id}. Only non-nil fields are sent, giving partial-update (PATCH-like) semantics.

type ValidPermissionsResponse 

type ValidPermissionsResponse struct {
	Permissions []string `json:"permissions"`
	Total       int      `json:"total,omitempty"`
	Service     string   `json:"service,omitempty"`
}

ValidPermissionsResponse is the result of GET /permissions/registry/valid-permissions.

type ValidateAPIKeyRequest 

type ValidateAPIKeyRequest struct {
	APIKey              string   `json:"api_key"`
	RequiredPermissions []string `json:"required_permissions,omitempty"`
	ExpectedAudience    string   `json:"expected_audience,omitempty"`
}

ValidateAPIKeyRequest is the body for POST /auth/validate-api-key.

type ValidationCacheOptions added in v0.10.0 

type ValidationCacheOptions struct {
	// TTL is how long a POSITIVE (valid) decision is trusted. Non-positive
	// disables the cache.
	TTL time.Duration
	// NegativeTTL is how long a NEGATIVE (answered, but not valid) decision is
	// trusted. Zero means DefaultValidationCacheNegativeTTL, clamped to never
	// exceed TTL. Negative disables caching of negatives (they always re-ask).
	NegativeTTL time.Duration
	// MaxEntries bounds the cache. Zero means DefaultValidationCacheMaxEntries.
	MaxEntries int
}

ValidationCacheOptions configures the validation cache. A zero TTL disables the cache entirely.

type ValidationCacheStats added in v0.10.0 

type ValidationCacheStats struct {
	// Enabled reports whether a cache is configured at all.
	Enabled bool
	// Hits is the number of validations served without an HTTP request.
	Hits uint64
	// Misses is the number of validations that had to call the auth service
	// (a cold key, or an expired entry).
	Misses uint64
	// Entries is the number of cached decisions currently held, live or expired.
	Entries int
}

ValidationCacheStats reports cache activity. It exists so a consumer can prove the cache is doing what it claims — a hot path that believes it is cached and is not has simply bought a dependency for nothing.

type Validator 

type Validator interface {
	ValidateToken(ctx context.Context, token string) (*Actor, error)
}

Validator resolves a bearer token to an Actor (identity + tenant + perms). A resource server's request middleware should depend on this, not on *Client.

type VerifyEmailConfirmRequest 

type VerifyEmailConfirmRequest struct {
	Token string `json:"token"`
}

VerifyEmailConfirmRequest is the body for POST /auth/verify-email/confirm.

type VerifyEmailSendRequest 

type VerifyEmailSendRequest struct {
	Email string `json:"email,omitempty"`
	OrgID string `json:"org_id,omitempty"`
}

VerifyEmailSendRequest is the body for POST /auth/verify-email/send.

type ViolationListResponse 

type ViolationListResponse struct {
	Violations []NetworkViolation `json:"violations"`
	Total      int                `json:"total,omitempty"`
	Count      int64              `json:"count,omitempty"`
}

ViolationListResponse lists access violations.

type VisualizationRequest 

type VisualizationRequest struct {
	OrgID              string `json:"org_id"`
	IncludeUsers       bool   `json:"include_users,omitempty"`
	IncludeTeams       bool   `json:"include_teams,omitempty"`
	IncludePermissions bool   `json:"include_permissions,omitempty"`
	MaxDepth           int    `json:"max_depth,omitempty"`
}

VisualizationRequest is the body for POST /zanzibar/stores/{store_id}/visualize/hierarchy. Matches OpenAPI schema VisualizationRequest (required: org_id).

type WatchStatusResponse 

type WatchStatusResponse struct {
	Available bool   `json:"available"`
	Channel   string `json:"channel,omitempty"`
	Message   string `json:"message"`
}

WatchStatusResponse is the result of GET /zanzibar/stores/{store_id}/watch/status. Matches OpenAPI schema WatchStatusResponse (required: available, message).

type WebAuthnConfigResponse 

type WebAuthnConfigResponse struct {
	RPID                string          `json:"rp_id,omitempty"`
	RPName              string          `json:"rp_name,omitempty"`
	Origin              string          `json:"origin,omitempty"`
	Origins             []string        `json:"origins,omitempty"`
	AttestationFormat   string          `json:"attestation,omitempty"`
	UserVerification    string          `json:"user_verification,omitempty"`
	Enabled             bool            `json:"enabled,omitempty"`
	Features            json.RawMessage `json:"features,omitempty"`
	SupportedAlgorithms json.RawMessage `json:"supported_algorithms,omitempty"`
	SupportedTransports []string        `json:"supported_transports,omitempty"`
	Timeout             int64           `json:"timeout,omitempty"`
}

WebAuthnConfigResponse is the result of GET /auth/passwordless/webauthn/config.

type WebAuthnCredential 

type WebAuthnCredential struct {
	ID         string `json:"id"`
	Name       string `json:"name,omitempty"`
	DeviceType string `json:"device_type,omitempty"`
	CreatedAt  string `json:"created_at,omitempty"`
	LastUsedAt string `json:"last_used_at,omitempty"`
	BackedUp   bool   `json:"backed_up,omitempty"`
}

WebAuthnCredential is a registered passkey/credential.

type WebAuthnCredentialListResponse 

type WebAuthnCredentialListResponse struct {
	Credentials []WebAuthnCredential `json:"credentials"`
	Count       int64                `json:"count,omitempty"`
}

WebAuthnCredentialListResponse lists a user's registered credentials.

type WebAuthnCredentialUpdate 

type WebAuthnCredentialUpdate struct {
	Name string `json:"name"`
}

WebAuthnCredentialUpdate renames a credential.

type WebAuthnRegistrationResult 

type WebAuthnRegistrationResult struct {
	CredentialID string `json:"credential_id,omitempty"`
	Success      bool   `json:"success,omitempty"`
	Message      string `json:"message,omitempty"`
	Verified     bool   `json:"verified,omitempty"`
}

WebAuthnRegistrationResult is returned when finishing a WebAuthn registration.

type WildcardCheckResponse 

type WildcardCheckResponse struct {
	Allowed bool `json:"allowed"`
}

WildcardCheckResponse is the result of GET /zanzibar/stores/{store_id}/check/wildcard. Matches OpenAPI schema WildcardCheckResponse (required: allowed).

type WriteAuthorizationModelRequest 

type WriteAuthorizationModelRequest struct {
	Model AuthorizationModel `json:"model"`
}

WriteAuthorizationModelRequest is the body for POST .../authorization-models.

type WriteAuthorizationModelResponse 

type WriteAuthorizationModelResponse struct {
	AuthorizationModelID string `json:"authorization_model_id"`
	Message              string `json:"message,omitempty"`
}

WriteAuthorizationModelResponse returns the immutable, versioned model id that subsequent checks and writes may pin to.

type WriteOperationResponse 

type WriteOperationResponse struct {
	Success bool   `json:"success"`
	Message string `json:"message"`
	// ConsistencyToken (a "zookie") identifies the revision this write produced.
	// Feed it back as CheckPermissionRequest.ConsistencyToken (or the *Request
	// consistency_token fields) to get a read-after-write consistent read. Empty
	// if the server issues none.
	ConsistencyToken string `json:"consistency_token,omitempty"`
}

WriteOperationResponse is the result of a tuple write/delete/grant/revoke. Matches OpenAPI schema WriteOperationResponse (required: success, message).

type ZanzibarMessageResponse 

type ZanzibarMessageResponse struct {
	Message string `json:"message"`
}

ZanzibarMessageResponse is the generic Zanzibar message envelope. Matches OpenAPI schema ZanzibarMessageResponse (required: message).

type ZanzibarStore added in v0.3.0 

type ZanzibarStore struct {
	// contains filtered or unexported fields
}

ZanzibarStore is a Zanzibar store with its id and caller token already bound. Get one from Client.Store. It is safe for concurrent use if the underlying Client is; it holds no mutable state of its own.

func (*ZanzibarStore) As added in v0.3.0 

func (s *ZanzibarStore) As(callerToken string) *ZanzibarStore

As returns a copy of this store bound to a different caller token — for per-request user tokens over a long-lived store handle.

func (*ZanzibarStore) Can added in v0.3.0 

func (s *ZanzibarStore) Can(ctx context.Context, subjectType, subjectID, permission, objectType, objectID string) (bool, error)

Can reports whether subject may perform permission on object. This is the call you will make most. 

ok, err := store.Can(ctx, "user", "alice", "view", "doc", "123")

FAILS CLOSED: any error returns false. Check the error — a false with a non-nil error means "could not decide", which is not the same as a denial and usually deserves a 503 rather than a 403.

func (*ZanzibarStore) CanAll added in v0.3.0 

func (s *ZanzibarStore) CanAll(ctx context.Context, checks ...CheckPermissionRequest) (bool, error)

CanAll reports whether EVERY check is allowed, in one round trip.

FAILS CLOSED twice over: an error is false, and so is an empty checks slice — "nothing was asked" is not "everything is permitted".

func (*ZanzibarStore) CanAny added in v0.3.0 

func (s *ZanzibarStore) CanAny(ctx context.Context, checks ...CheckPermissionRequest) (bool, error)

CanAny reports whether AT LEAST ONE check is allowed, in one round trip. An empty checks slice is false.

func (*ZanzibarStore) CanID added in v0.3.0 

func (s *ZanzibarStore) CanID(ctx context.Context, subject, permission, object string) (bool, error)

CanID is Can for callers who already hold combined "type:id" strings.

func (*ZanzibarStore) ID added in v0.3.0 

func (s *ZanzibarStore) ID() string

ID returns the bound store id.

func (*ZanzibarStore) Relate added in v0.3.0 

func (s *ZanzibarStore) Relate(ctx context.Context, subjectType, subjectID, relation, objectType, objectID string) error

Relate writes one relationship tuple: subject #relation@ object. 

err := store.Relate(ctx, "user", "alice", "owner", "doc", "123")

Idempotent server-side: writing a tuple that already exists is not an error.

func (*ZanzibarStore) RelateID added in v0.3.0 

func (s *ZanzibarStore) RelateID(ctx context.Context, subject, relation, object string) error

RelateID is Relate for callers holding combined "type:id" strings.

func (*ZanzibarStore) RelateUntil added in v0.8.0 

func (s *ZanzibarStore) RelateUntil(ctx context.Context, subject, relation, object string, expires time.Time) error

RelateUntil writes a relationship that expires.

Time-boxing exists on the wire and had no ergonomic path, so callers granted permanent access for temporary needs — a permissions leak created by the SDK's own surface rather than by anything the customer did wrong.

func (*ZanzibarStore) RelationsOn added in v0.3.0 

func (s *ZanzibarStore) RelationsOn(ctx context.Context, objectType, objectID, relation string) ([]RelationshipEntry, error)

RelationsOn lists the stored relationship tuples on one object — what is actually written down, as opposed to what the check engine derives from it. Pass relation "" for all relations.

func (*ZanzibarStore) Unrelate added in v0.3.0 

func (s *ZanzibarStore) Unrelate(ctx context.Context, subjectType, subjectID, relation, objectType, objectID string) error

Unrelate removes one relationship tuple. Removing an absent tuple is not an error.

func (*ZanzibarStore) UnrelateID added in v0.3.0 

func (s *ZanzibarStore) UnrelateID(ctx context.Context, subject, relation, object string) error

UnrelateID is Unrelate for callers holding combined "type:id" strings.

func (*ZanzibarStore) WhatCan added in v0.3.0 

func (s *ZanzibarStore) WhatCan(ctx context.Context, subject, permission, objectType string) ([]string, error)

WhatCan answers "which objects of this type may this subject act on?" — the query behind every filtered index page ("show me the documents alice can view").

Returns combined ids as the server gives them. A nil error with an empty slice means the subject may act on nothing, which is a real answer.

func (*ZanzibarStore) WhoCan added in v0.3.0 

func (s *ZanzibarStore) WhoCan(ctx context.Context, object, permission string) ([]string, error)

WhoCan answers "who may act on this object?" — the query behind every sharing dialog. Group memberships are expanded to their members by default.

func (*ZanzibarStore) Why added in v0.3.0 

func (s *ZanzibarStore) Why(ctx context.Context, subject, permission, object string) (*CheckPermissionResponse, error)

Why is CanID with the server's explanation attached — the reason and the relationship path it followed. Use it when a decision is surprising and you want to see how the server got there, rather than guessing from the tuples.

Source Files

View all Source files

Directories

Path Synopsis
Package authclienttest provides test doubles for the ab0t Auth Service client.
 Package authclienttest provides test doubles for the ab0t Auth Service client.
Package authmw is net/http middleware that gates routes on the ab0t Auth Service.
 Package authmw is net/http middleware that gates routes on the ab0t Auth Service.
cmd
ab0t-auth command
Command ab0t-auth is a command-line client for the ab0t Auth Service.
 Command ab0t-auth is a command-line client for the ab0t Auth Service.
examples
gate command
Command gate is a complete, runnable example of the thing this SDK is mostly used for: putting an ab0t Auth Service check in front of an HTTP route.
 Command gate is a complete, runnable example of the thing this SDK is mostly used for: putting an ab0t Auth Service check in front of an HTTP route.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.