Skip to main content
Version: 2.x (Latest)

gRPC API

Authorizer exposes its service over native gRPC, alongside the GraphQL and REST surfaces. All three are backed by the same service layer and the same Protocol Buffers definition, so they behave identically — gRPC just gives you a strongly-typed, high-performance binary transport for server-to-server calls.

Table of Contents

Service & transport​

PropertyValue
Proto packageauthorizer.v1
ServicesAuthorizerService (public) + AuthorizerAdminService (admin)
BSR modulebuf.build/authorizerdev/authorizer
Port--grpc-port (default 9091) — same server, both services
TLS--grpc-tls-cert + --grpc-tls-key; --grpc-insecure for dev
Server reflection--enable-grpc-reflection (default true)
Health checkinggrpc.health.v1.Health (always registered)
JSON field casing (REST)snake_case via UseProtoNames — payloads match GraphQL byte-for-byte

The gRPC server is enabled by default. Auth flows over gRPC exactly as they do over REST: attach the user's credential as request metadata — authorization: Bearer <access_token> — or forward the cookie header from a browser session.

Session cookies over gRPC and REST​

Cookie-setting flows (Signup, Login, Session, VerifyEmail, VerifyOtp, and MFA challenge paths) emit session/MFA cookies as set-cookie gRPC response metadata. Over native gRPC, clients that need cookie-based auth must read these metadata headers and forward the Cookie value on subsequent calls. Over REST, the grpc-gateway promotes them to real Set-Cookie HTTP headers (previously they surfaced as Grpc-Metadata-Set-Cookie, which browsers ignored).

CookiegRPC metadata / REST headerSet by
App session (cookie_session, cookie_session_domain)set-cookie → Set-CookieSignup, Login, Session, VerifyEmail, VerifyOtp
MFA challenge (mfa)set-cookie → Set-CookieLogin, ForgotPassword, ResendOtp when MFA is required
Admin session (authorizer-admin)set-cookie → Set-CookieAdminLogin, AdminSession

Admin auth also accepts x-authorizer-admin-secret as incoming metadata (mirrored from the REST X-Authorizer-Admin-Secret header).

Protobuf schema​

The schema is published to the Buf Schema Registry as the module buf.build/authorizerdev/authorizer (all messages live in a single authorizer.v1 package). You can generate a typed client for any language without copying .proto files around:

# buf.gen.yaml
version: v2
inputs:
  - module: buf.build/authorizerdev/authorizer
plugins:
  - remote: buf.build/grpc/go
    out: gen
    opt: paths=source_relative
  - remote: buf.build/protocolbuffers/go
    out: gen
    opt: paths=source_relative
buf generate

Swap the remote plugins for buf.build/grpc/python, .../grpc/web, etc. to target other languages.

Other options:

  • Vendor the source — the .proto files live in the proto/ directory of the repo; run buf generate or protoc against them directly.
  • No protos at all — since server reflection is enabled by default, grpcurl, Postman, etc. can call the API without any schema files.
  • Skip codegen — the official Go, JavaScript, and Python SDKs wrap the API for you.

Public Methods​

Each message mirrors its GraphQL/REST counterpart — see the linked GraphQL API reference anchor for field-level details.

Response types. Methods return the bare domain message — there is no per-RPC wrapper. Signup, Login, VerifyEmail, VerifyOtp, and Session return AuthResponse; Profile returns User; Meta returns Meta. This keeps the gRPC, REST, and GraphQL payloads identical (snake_case field names, no auth / user / meta envelope keys). Request messages are likewise flat — send the RPC input fields directly.

Example — Login returns a flat AuthResponse (not { "auth": { … } }):

{
  "message": "Logged in successfully",
  "access_token": "eyJhbGciOiJIUzI1NiIs…",
  "expires_in": 1718534400,
  "user": { "id": "…", "email": "jane@example.com" }
}

Meta​

Public. Server feature flags & provider availability. Mirrors meta.

Signup​

Public. Register a new user. Mirrors signup.

Login​

Public. Authenticate with email/phone + password. Returns tokens, or an MFA challenge flag when OTP/TOTP is enabled. Mirrors login.

MagicLinkLogin​

Public. Start a passwordless login; emails a magic link. Mirrors magic_link_login.

VerifyEmail​

Public. Complete email verification using the token from the verification email. Mirrors verify_email.

ResendVerifyEmail​

Public. Re-send the email-verification message. Mirrors resend_verify_email.

VerifyOtp​

Public. Complete an MFA challenge by submitting the email/phone OTP. Mirrors verify_otp.

ResendOtp​

Public. Re-send the MFA OTP. Mirrors resend_otp.

SkipMfaSetup​

Public. Completes an in-progress, token-withheld MFA offer by recording an explicit decline, then issues the withheld access token. Fails with FAILED_PRECONDITION when MFA is org-enforced (--enforce-mfa). Mirrors skip_mfa_setup.

LockMfa​

Public. Records that the caller lost access to their only MFA factor(s); only allowed with no verified Email/SMS OTP fallback enrolled. Does not issue a token — the account requires admin recovery afterward. Mirrors lock_mfa.

EmailOtpMfaSetup​

Public (dual-mode). Sends a one-time code to the caller's own email and creates an unverified email-OTP MFA enrollment — either for an already-authenticated caller adding a second factor, or a caller in the withheld first-time-offer state identified by the MFA session cookie. Mirrors email_otp_mfa_setup.

SmsOtpMfaSetup​

Public (dual-mode). Same as EmailOtpMfaSetup, for SMS. Mirrors sms_otp_mfa_setup.

ForgotPassword​

Public. Start password reset; emails a reset link. Mirrors forgot_password.

ResetPassword​

Public. Set a new password using the reset token. Mirrors reset_password.

Session​

Authenticated. Refresh / fetch the current session. Mirrors session.

Profile​

Authenticated. The authenticated user's profile. Mirrors profile.

UpdateProfile​

Authenticated. Update the authenticated user's profile. Mirrors update_profile.

DeactivateAccount​

Authenticated. Deactivate (soft-delete) the authenticated user's account. Mirrors deactivate_account.

Logout​

Authenticated. Invalidate the current session. Mirrors logout.

Revoke​

Public. Revoke a refresh token. Mirrors revoke.

ValidateJwtToken​

Public. Validate a JWT and optional required relations. Mirrors validate_jwt_token.

ValidateSession​

Authenticated. Validate a session cookie and required relations. Mirrors validate_session.

CheckPermissions​

Authenticated. Batch-evaluate FGA (relation, object) checks. Mirrors check_permissions.

ListPermissions​

Authenticated. List objects/relations the subject can access. Mirrors list_permissions.

Authorizer Admin Methods​

The AuthorizerAdminService is served on the same gRPC port and address as AuthorizerService. All admin methods require super-admin authentication via the x-authorizer-admin-secret request metadata (the admin secret configured with --admin-secret) or an authorizer.admin session cookie. Except AdminLogin, which does not require an existing session.

Admin Authentication​

AdminLogin​

Public (for admin-secret). Authenticate as super-admin with the admin secret. Returns an auth response with session token.

AdminLogout​

Admin-only. Invalidate the current admin session.

AdminSession​

Admin-only. Verify the current admin session is valid.

AdminMeta​

Admin-only. Get admin-level server metadata (version, feature flags with admin-only fields).

User Management​

Users​

Admin-only. List all users with pagination. Mirrors _users.

User​

Admin-only. Get a specific user by id or email. Mirrors _user.

UpdateUser​

Admin-only. Update user profile fields (email, roles, name, etc.). Mirrors _update_user.

DeleteUser​

Admin-only. Delete a user by email and all associated OTP/verification data. Mirrors _delete_user.

VerificationRequests​

Admin-only. List pending verification requests with optional pagination. Mirrors _verification_requests.

Access Control​

RevokeAccess​

Admin-only. Revoke a user's access (set revoked_timestamp) and fire the user.access_revoked webhook. Mirrors _revoke_access.

EnableAccess​

Admin-only. Re-enable a previously revoked user (clear revoked_timestamp) and fire the user.access_enabled webhook. Mirrors _enable_access.

InviteMembers​

Admin-only. Invite users to the platform by email with an invitation link. Mirrors _invite_members.

Webhook Management​

AddWebhook​

Admin-only. Register a new webhook for an event. Mirrors _add_webhook.

UpdateWebhook​

Admin-only. Update an existing webhook (endpoint, headers, enabled state, etc.). Mirrors _update_webhook.

DeleteWebhook​

Admin-only. Delete a webhook by id. Mirrors _delete_webhook.

GetWebhook​

Admin-only. Get a webhook by id. Mirrors _webhook.

Webhooks​

Admin-only. List all webhooks with pagination. Mirrors _webhooks.

WebhookLogs​

Admin-only. List webhook delivery logs with optional pagination and webhook_id filter. Mirrors _webhook_logs.

TestEndpoint​

Admin-only. Send a test webhook payload to an endpoint and return the HTTP response. Mirrors _test_endpoint.

Email Template Management​

AddEmailTemplate​

Admin-only. Create a new email template for an event. Mirrors _add_email_template.

UpdateEmailTemplate​

Admin-only. Update an email template. Mirrors _update_email_template.

DeleteEmailTemplate​

Admin-only. Delete an email template by id. Mirrors _delete_email_template.

EmailTemplates​

Admin-only. List email templates with pagination. Mirrors _email_templates.

Audit Logs​

AuditLogs​

Admin-only. Retrieve audit log entries with optional filtering by actor, action, or resource and pagination. Mirrors _audit_logs.

Authorization (FGA)​

Manage the embedded fine-grained authorization (FGA) engine. See Authorization (FGA) for the conceptual model.

FgaGetModel​

Admin-only. Retrieve the active authorization model as FGA DSL. An empty store returns an empty model (not an error).

FgaWriteModel​

Admin-only. Install a new authorization model version from FGA DSL. Models are versioned and append-only. Audited.

FgaWriteTuples​

Admin-only. Write (persist) relationship tuples. Audited.

FgaDeleteTuples​

Admin-only. Delete relationship tuples. Audited.

FgaReadTuples​

Admin-only. Read stored tuples with optional filtering by user, relation, or object and pagination.

FgaListUsers​

Admin-only. List fully-qualified user ids that have a relation on an object (reveals the access graph).

FgaExpand​

Admin-only. Expand the relationship/userset tree for a relation on an object (useful for debugging).

FgaReset​

Admin-only. Delete the entire fine-grained authorization store (model, all versions, and all tuples) and start fresh. Refused if any tuples still exist. Destructive and audited.

Client Registry​

Manage machine/workload identity clients (service_account and similar client types). See the Client Registry guide for the conceptual model.

CreateClient​

Admin-only. Provision a new client and return the generated client secret exactly once.

UpdateClient​

Admin-only. Update a client's name, description, allowed scopes, or active state. Never touches the secret.

DeleteClient​

Admin-only. Delete a client by id, cascading to its trusted issuers.

RotateClientSecret​

Admin-only. Replace the stored client secret with a fresh one, returned exactly once. The old secret stops validating immediately.

GetClient​

Admin-only. Get a single client by id. The client secret is never surfaced.

Clients​

Admin-only. List clients with pagination. Client secrets are never surfaced.

Trusted Issuers​

Manage external JWT issuers used for RFC 7523 private_key_jwt client assertions. See Workload Identity.

AddTrustedIssuer​

Admin-only. Register an external issuer for a client. subject_claim defaults to sub when omitted.

UpdateTrustedIssuer​

Admin-only. Update an issuer's name, JWKS URL, expected audience, active state, or SPIFFE refresh hint.

DeleteTrustedIssuer​

Admin-only. Delete a trusted issuer by id.

GetTrustedIssuer​

Admin-only. Get a single trusted issuer by id.

TrustedIssuers​

Admin-only. List trusted issuers, optionally filtered by client id, with pagination.

SAML IdP​

Manage Authorizer acting as a SAML 2.0 identity provider for downstream service providers, plus IdP signing-key rotation. See SAML IdP.

CreateSamlServiceProvider​

Admin-only. Register a downstream SP that Authorizer issues signed assertions to.

UpdateSamlServiceProvider​

Admin-only. Update a downstream SP's name, endpoints, certificate, attribute mapping, or active state.

DeleteSamlServiceProvider​

Admin-only. Delete a downstream SP by id.

GetSamlServiceProvider​

Admin-only. Get a single downstream SP by id.

ListSamlServiceProviders​

Admin-only. List downstream SPs for an org.

RotateSamlIdpCert​

Admin-only. Generate a new current signing keypair for an org's SAML IdP, demoting the previous current key.

RetireSamlIdpKey​

Admin-only. Retire a published-but-not-signing SAML IdP key by id.

ListSamlIdpKeys​

Admin-only. List all SAML IdP signing keys for an org.

ImportSamlSpMetadata​

Admin-only. Parse pasted SP metadata XML and return fields to prefill a create call. Performs no remote fetch and creates no record.

Calling with grpcurl​

With reflection enabled you can explore and call the service directly:

# List services
grpcurl -plaintext localhost:9091 list

# Describe a method
grpcurl -plaintext localhost:9091 describe authorizer.v1.AuthorizerService.Login

# Login (public) — response is a flat AuthResponse; check -H for set-cookie metadata
grpcurl -plaintext \
  -d '{"email":"jane@example.com","password":"Test@123"}' \
  localhost:9091 authorizer.v1.AuthorizerService/Login

# Check permissions (authenticated)
grpcurl -plaintext \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -d '{"checks":[{"relation":"can_view","object":"document:1"}]}' \
  localhost:9091 authorizer.v1.AuthorizerService/CheckPermissions
{
  "results": [
    { "relation": "can_view", "object": "document:1", "allowed": true }
  ]
}

Drop -plaintext and use the TLS material when --grpc-tls-cert / --grpc-tls-key are configured.

Health checks​

The standard gRPC health-checking protocol is registered, so Kubernetes grpc liveness/ readiness probes work out of the box:

livenessProbe:
  grpc:
    port: 9091

Or with grpc-health-probe / grpcurl:

grpcurl -plaintext localhost:9091 grpc.health.v1.Health/Check
# {"status": "SERVING"}

Errors​

gRPC returns standard status codes; the HTTP REST gateway maps these to HTTP statuses. Common cases:

StatusMeaning
UNAUTHENTICATEDMissing or invalid credentials.
PERMISSION_DENIEDExplicit user not permitted for the caller.
FAILED_PRECONDITIONFGA not enabled (--fga-store unset).
INVALID_ARGUMENTValidation failure (e.g. > 100 checks).

See also​

  • REST API — the same operations as JSON over HTTP (/v1).
  • GraphQL API — the full field-level reference and complete auth surface.
  • MCP Server — exposing check_permissions / list_permissions to AI agents.