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)

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

Protobuf schema​

The schema is published to the Buf Schema Registry as the module buf.build/authorizerdev/authorizer (package authorizer.v1, with shared messages in authorizer.common.v1). 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.

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.

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.

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.CheckPermissions

# 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.