Skip to main content

The Authzed API

Authzed exposes its APIs via gRPC and publishes its Protobuf Definitions to the Buf Registry.

The API can be accessed by client libraries or zed, the Authzed command-line tool.

Client Libraries

While any developer can generate their own clients from the public Authzed Protobuf Definitions, the Authzed team officially supports and maintains client libraries for a variety of languages. If you are interested in additional language support, feel free to reach out.

Official clients leverage their language's gRPC ecosystem to provide an abstraction for each version of the Authzed API. For example, in Go, constructing a client is no different from creating any other gRPC connection and can use any of the ecosystem's gRPC DialOption to configure its connection.

The list of the officially maintained client libraries includes:

Versions

Versioning & Deprecation Policy

APIs are versioned by their Protobuf package and version compatibility is enforced by the Buf Breaking Rules. New Messages, Fields, Services, and RPCs can be added to existing APIs as long as existing calls continue to exhibit the same behavior.

When an API version is marked as deprecated, the duration of its continued support will be announced.

During this deprecation period, Authzed reserves the right to take various actions to users and clients using deprecated APIs:

  • Email users
  • Print warning messages from official clients
  • Purposely disrupt service near the end of the period

authzed.api.v1

The v1 Authzed API is a full redesign of the initial v0 APIs.

API Docs

gRPC Documentation can be found in the Buf Registry.

Changes

  • Consistency is now configurable on a per-request basis. Schema Read/Write are always fully consistent
  • Schema Read/Write now operates on all definitions at once
  • Relationships are now composed of an Object and Subject references and the relation between them
  • DeleteRelationships was added to enable bulk removal of Relationships
  • Preconditions for WriteRelationships/DeleteRelationships are now expressed via Relationship filters
Legacy API versions

authzed.api.v1alpha1

A pre-release of some work-in-progress APIs for the eventual v1 release.

API Docs

gRPC Documentation can be found on the Buf Registry.

Changes

  • A new Schema language replaces Namespace Configs. Existing v0 NamespaceConfigs can be read from the SchemaRead() API.

authzed.api.v0

v0 is the first iteration of the Authzed API. It strived to be as accurate to the description of the Zanzibar APIs as possible.

API Docs

gRPC Documentation can be found in the v0 docs or the Buf Registry.

Caveats

This API did not originally have a Protobuf package defined and was migrated to have one. While the API can be called with or without the authzed.api.v0 prefix, some tools built to use the gRPC Reflection API will not work with the prefixless form. This had no effect on any official tooling or client libraries as all stable releases have always used the fully prefixed names of RPCs.