Authorization API Reference

Keymate exposes a gRPC-based Authorization API for fine-grained access control decisions. This API implements the Zanzibar model, allowing applications to check permissions based on relationship tuples.

Scope

This reference covers the public-facing Authorization API that external applications use to:

• Evaluate authorization decisions (Check, BatchCheck)
• Query accessible objects (ListObjects, ListUsers)
• Manage relationship tuples (Read, Write)
• Inspect permission graphs (Expand)

note

Internal platform services (User Management, Audit, Event Hub) use separate APIs not documented here. This page focuses on the authorization endpoints available to integrating applications.

Definitions

Term	Description
Store	Isolated authorization data container for a tenant
Tuple	A relationship record: user:alice → viewer → document:budget
Relation	The type of relationship (e.g., viewer, editor, owner)
Object	The resource being accessed (e.g., document:budget-2024)
User	The entity requesting access (user, group, or service account)
Authorization Model	Schema defining valid object types, relations, and inheritance rules
Userset	A computed set of users derived from relations and conditions

---

Core Methods

Method	Description
Check	Evaluate a single authorization decision
BatchCheck	Evaluate multiple authorization decisions in one call
Read	Read relationship tuples matching a filter
Write	Create or delete relationship tuples
Expand	Expand a userset to see the permission graph
ListObjects	List all objects a user can access with a given relation
ListUsers	List all users who have a given relation to an object

---

Store Management Methods

Method	Description
CreateStore	Create a new authorization store for a tenant
GetStore	Retrieve store metadata
ListStores	List all stores
DeleteStore	Delete a store and all its data

---

Authorization Model Methods

Method	Description
ReadAuthorizationModel	Retrieve a specific authorization model version
WriteAuthorizationModel	Deploy a new authorization model
ReadChanges	Read the changelog of tuple modifications

---

Request & Response Messages

CheckRequest

message CheckRequest {
  string store_id = ...;
  string authorization_model_id = ...;
  TupleKey tuple_key = ...;
  Context context = ...;
}

message TupleKey {
  string user = ...;
  string relation = ...;
  string object = ...;
}

CheckResponse

message CheckResponse {
  bool allowed = ...;
  string resolution = ...;
}

WriteRequest

message WriteRequest {
  string store_id = ...;
  string authorization_model_id = ...;
  TupleKeys writes = ...;
  TupleKeys deletes = ...;
}

ListObjectsRequest

message ListObjectsRequest {
  string store_id = ...;
  string authorization_model_id = ...;
  string type = ...;
  string relation = ...;
  string user = ...;
  Context context = ...;
}

ListObjectsResponse

message ListObjectsResponse {
  repeated string objects = ...;
}

---

Minimal Example

A permission check to verify if a user can view a document:

// Request
CheckRequest {
  store_id: "store_01H..."
  tuple_key: {
    user: "user:jane"
    relation: "viewer"
    object: "document:budget-2024"
  }
}

// Response
CheckResponse {
  allowed: true
  resolution: "direct"
}

Invalid Example

Missing required store_id field:

// ❌ Invalid - store_id is required
CheckRequest {
  tuple_key: {
    user: "user:jane"
    relation: "viewer"
    object: "document:budget-2024"
  }
}

// Error Response
{
  code: INVALID_ARGUMENT
  message: "store_id is required"
}

---

Authorization Flow

---

Allowed Values

Resolution Types

Value	Meaning
direct	User has a direct tuple granting access
computed	Access derived from another relation (e.g., editor implies viewer)
conditional	Access granted based on context conditions

---

Notes

warning

Rate Limits: The Authorization API enforces rate limits per store. Batch operations (BatchCheck) are more efficient than multiple single Check calls.

tip

Best Practice: Use ListObjects for UI filtering (show only accessible items) and Check for enforcement at access time.

---

Used By

• ReBAC — Relationship-Based Access Control concept
• FGA Engine Overview — Fine-grained authorization engine component details

---

Related Docs

API Overview

REST and gRPC API architecture overview

Error Codes

Platform error codes and troubleshooting

Authorization Models

ABAC, RBAC, ReBAC, and PBAC concepts

FGA Engine

Fine-grained authorization engine component