Authzed Java Client

This repository houses the Java client library for SpiceDB, a database and service that can store your application's permissions.

Developers create a schema that models their permissions requirements and use a client library, such as this one, to apply the schema to the database, insert data into the database, and query the data to efficiently check permissions in their applications.

You can find more info on each API on the SpiceDB API reference documentation. Additionally, Protobuf API documentation can be found on the Buf Registry SpiceDB API repository. Documentation for the latest Java client release is available as Javadoc.

See CONTRIBUTING.md for instructions on contributing and performing 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 practices to integrate an application with SpiceDB.

Installation

This project is packaged as the artifact authzed under the com.authzed.api group on Maven Central. You can find the commands for installing the jar for various JVM toolchains on the Maven Central Artifact Page.

Most commonly, if you are using Maven you can add the following to your pom.xml:

<dependencies>
    <dependency>
        <groupId>com.authzed.api</groupId>
        <artifactId>authzed</artifactId>
        <version>1.4.0</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-api</artifactId>
        <version>1.72.0</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-stub</artifactId>
        <version>1.72.0</version>
    </dependency>
</dependencies>

If you are using Gradle then add the following to your build.gradle file:

dependencies {
    implementation "com.authzed.api:authzed:1.4.1"
    implementation 'io.grpc:grpc-api:1.72.0'
    implementation 'io.grpc:grpc-stub:1.72.0'
}

Initializing a client

package org.example;

import com.authzed.api.v1.PermissionsServiceGrpc;
import com.authzed.grpcutil.BearerToken;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

public class PermissionServiceExample {
    public static void main(String[] args) {
        // establish a connection to Authzed
        ManagedChannel channel = ManagedChannelBuilder
                .forTarget("grpc.authzed.com:443")
                .useTransportSecurity()
                .build();

        // get the bearer token from your Authzed dashboard (or from https://app.authzed.cloud)
        BearerToken bearerToken = new BearerToken("t_your_token_here_1234567deadbeef");
        
        // create the client
        PermissionsServiceGrpc.PermissionsServiceBlockingStub permissionsService = PermissionsServiceGrpc
                .newBlockingStub(channel)
                .withCallCredentials(bearerToken);
    }
}

In case of a local development instance of SpiceDB without TLS, configure your ManagedChannel as follows:

ManagedChannel channel = ManagedChannelBuilder
    .forTarget("localhost:50051")
    .usePlaintext()
    .build();

Calling CheckPermission

Request and Response types are located in their respective gRPC Service packages and common types can be found in the Core package. Referring to the Authzed ProtoBuf Documentation is useful for discovering these APIs.

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

The following example initializes a permission client, performs a CheckPermission call and prints the result.

package org.example;

import com.authzed.api.v1.*;
import com.authzed.grpcutil.BearerToken;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

public class ClientExample {
    public static void main(String[] args) {
        ManagedChannel channel = ManagedChannelBuilder
                .forTarget("localhost:50051")
                .usePlaintext()
                .build();

        BearerToken bearerToken = new BearerToken("t_your_token_here_1234567deadbeef");
        PermissionsServiceGrpc.PermissionsServiceBlockingStub permissionsService = PermissionsServiceGrpc
                .newBlockingStub(channel)
                .withCallCredentials(bearerToken);


        CheckPermissionRequest request = CheckPermissionRequest.newBuilder()
                .setConsistency(
                        Consistency.newBuilder()
                                .setMinimizeLatency(true)
                                .build())
                .setResource(
                        ObjectReference.newBuilder()
                                .setObjectType("blog/post")
                                .setObjectId("1")
                                .build())
                .setSubject(
                        SubjectReference.newBuilder()
                                .setObject(
                                        ObjectReference.newBuilder()
                                                .setObjectType("blog/user")
                                                .setObjectId("emilia")
                                                .build())
                                .build())
                .setPermission("read")
                .build();

        // Is Emilia in the set of users that can read post #1?
        try {
            CheckPermissionResponse response = permissionsService.checkPermission(request);
            System.out.println("result: " + response.getPermissionship().getValueDescriptor().getName());
        } catch (Exception e) {
            System.out.println("Failed to check permission: " + e.getMessage());
        }
    }
}

More examples

See the examples directory for more code snippets.