OpenFGA API

The OpenFGA API Protocol Buffers definitions.

About

OpenFGA is an open source Fine-Grained Authorization solution inspired by Google's Zanzibar paper. It was created by the FGA team at Auth0/Okta based on Auth0 Fine-Grained Authorization (FGA), available under a permissive license (Apache-2) and welcomes community contributions.

OpenFGA is designed to make it easy for application builders to model their permission layer, and to add and integrate fine-grained authorization into their applications. OpenFGA’s design is optimized for reliability and low latency at a high scale.

Usage

Buf is used to manage, package, and generate source code from the protocol buffer definitions. The API definitions are pushed to the buf.build/openfga/api repository in the Buf Registry.

You can find various SDKs autogenerated by buf based on the protobuf definitions here: https://buf.build/openfga/api/sdks/main:protobuf

For example, to import the definitions in Go you can do so via the following command:

go get go.buf.build/openfga/go/openfga/api

If you are looking for the currently supported OpenFGA HTTP SDKs, you can find them here: https://github.com/openfga/sdk-generator#currently-supported-sdks

Contributing

Building the Generated Sources

To generate source code from the protobuf definitions contained in this project you can run the following command:

Note: You must have Buf CLI installed to run the following command.

make buf-gen

The command above will generate source code in the proto/ directory. It will also configure a local git hook to check that files requiring auto-generation after .proto changes have been updated. There are some cases where that git hook may be overly strict. In those cases you can bypass it with commit --no-verify.

Use the generated sources in OpenFGA

1. Generate the sources as above
2. In the proto directory execute the following commands:

   go mod init go.buf.build/openfga/go/openfga/api
   go mod tidy

3. In OpenFGA, add the following line to your go.mod:

   replace github.com/openfga/api/proto => /path/to/proto

Generating OpenAPI Documentation

To generate the OpenAPI documentation from the protobuf sources you can run the following commands:

Note: You must have jq installed to run the format step below

./buf.gen.yaml
./scripts/update_swagger.sh docs/openapiv2/apidocs.swagger.json
buf format -w

Or you can just use

make

See CONTRIBUTING.

Author

OpenFGA

License

This project is licensed under the Apache-2.0 license. See the LICENSE file for more info.