authzed-go

README

Authzed Go Client

This repository houses the official Go client library for Authzed and SpiceDB.

SpiceDB is a database system for managing security-critical permissions checking.

SpiceDB acts as a centralized service that stores authorization data. Once stored, data can be performantly queried to answer questions such as "Does this user have access to this resource?" and "What are all the resources this user has access to?".

Authzed operates the globally available, serverless database platform for SpiceDB.

Supported client API versions:

• v1
• v1alpha1

You can find more info about the API in the Authzed Documentation API Reference or the Authzed API Buf Registry repository.

See CONTRIBUTING.md for instructions on how to contribute and perform common tasks like building the project and running tests.

Getting Started

We highly recommend following the Protecting Your First App guide to learn the latest best practice to integrate an application with Authzed.

Basic Usage

Installation

If you're using a modern version of Go, run the following commands to add dependencies to your project:

go get github.com/authzed/authzed-go
go get github.com/authzed/grpcutil

grpcutil is not strictly required, but greatly reduces the boilerplate required to create a client in the general case.

Initializing a client

The NewClient() constructor is the recommended method for creating a client.

Because this library is using gRPC under the hood, you are free to leverage the wealth of functionality provided via DialOptions.

In order to successfully connect, you will have to provide a Bearer Token with your own API Token from the Authzed dashboard in place of t_your_token_here_1234567deadbeef in the following example:

import (
	"github.com/authzed/authzed-go/v1"
	"github.com/authzed/grpcutil"
)

...

client, err := authzed.NewClient(
	"grpc.authzed.com:443",
	grpcutil.WithSystemCerts(grpcutil.VerifyCA),
	grpcutil.WithBearerToken("t_your_token_here_1234567deadbeef"),
)
if err != nil {
	log.Fatalf("unable to initialize client: %s", err)
}

Performing an API call

Requests and response types are located in a package under proto/ respective to their API version.

Because of the verbosity of these types, we recommend writing your own functions/methods to create these types from your existing application's models.

import (
	"github.com/authzed/authzed-go/proto/authzed/api/v1"
	"github.com/authzed/authzed-go/v1"
	"github.com/authzed/grpcutil"
)

...

emilia := &pb.SubjectReference{Object: &v1.ObjectReference{
	ObjectType: "blog/user",
	ObjectId:  "emilia",
}}

firstPost := &pb.ObjectReference{
	ObjectType: "blog/post",
	ObjectId: "1",
}

resp, err := client.CheckPermission(ctx, &pb.CheckPermissionRequest{
	Resource: firstPost,
	Permission: "read",
	Subject: emilia,
})
if err != nil {
    log.Fatalf("failed to check permission: %s", err)
}

if resp.Permissionship == pb.CheckPermissionResponse_PERMISSIONSHIP_HAS_PERMISSION {
	log.Println("allowed!")
}