Skip to main content

Quick Start

note

This page makes use of Zanzibar terminology and namespace configuration. Please refer to the current Authzed terminology and schema configuration.

Getting Started#

To get started using the Authzed Permissions API, a Tenant needs to be created.

The Tenant contains the configuration for how permissions are resolved (called Namespaces), as well as a Token for use by clients to call the API.

Creating an organization#

To begin, visit the Authzed Management Dashboard, where you will be prompted to create an organization. An organization is a logical set of tenants, managed together.

An image of the organization creation screen

Creating a tenant#

Once you've created your organization, click the Create Tenant button to show the tenant creation dialog:

An image of the create tenant screen

Enter a unique slug for the tenant (which will be used as the prefix for all your Namespaces), a human-readable title and a quick description of your tenant.

For now, it is recommended to create a Development tenant.

Configuring the tenant#

An image of the tenant overview screen

A Tenant consists of Namespaces, along with permissions on who can interact with those namespaces via the API.

Loading a namespace from an example (or playground)#

To quickly add some namespaces to our new development tenant for testing, we can choose one of the options on the Namespaces screen, such as loading namespaces from a shared Playground link or from an existing example permissions model.

Here, we'll choose to setup a basic RBAC permissions model. To do so, click the QUICK START FROM EXAMPLE button, and choose LOAD EXAMPLE DATA for the "Basic RBAC" permissions model:

An image of the RBAC-like example

This will load the namespace configurations for the permissions system into our tenant:

An image of the tenant overview screen with namespaces loaded

Creating a token and granting it access to the tenant#

Showing permissions#

Once your tenant has been created and populated, we need to create and grant permission on that tenant an authorization Token, to allow for API access.

An image of the API permissions tab

Click the API ACCESS PERMISSIONS tab to view all users and Clients that have the ability to make API calls to this tenant.

Right now, the only permission should be yourself as a user, but we need to add a Client (with a Token) so we can make calls programatically.

Adding permissions#

To do so, click the GRANT TENANT ACCESS TO A CLIENT OR USER button. This will display a dialog to add a user (or client) to the permissions list for the tenant.

Since we do not yet have a client, click within the box (or start typing), and a dropdown will be displayed with an option to create a new client. Click CREATE A CLIENT to continue.

An image of the add permissions screen

Adding a client#

An image of the create client screen

In the Create Client dialog, enter a descriptive title and description for the new client. For example, if this client is intended to be used by your backend, a good title might be Backend Client.

Create Create Client to create the new client.

note

The client is automatically grant it Write permission on the tenant. This automatically granted permission allows the client's tokens to read and write both namespace configurations and tuples. This permission can be changed (or revoked) in the tenant's API Access Permissions tab.

Adding a token#

Once the client is created, a dialog will automatically be displayed to generate a new Token for the client. The Token will be used in the Authorization header of the Authzed Permissions API to authenticate to Authzed on behalf of the client.

An image of the create token screen

Click Create Token to create the token with the default title and note.

An image of the token screen

Once created make sure to copy down the token value. It will not be repeated or retrievable again!

note

The created token, by being attached to the client created above, will be able to Write on the tenant.

Installing the Authzed client library#

Now that we have a valid Tenant and Token, we can add code to our application to make use of the permissions API.

To begin, we recommend installing a client library for the language that your application is written in. If a client library does not exist, have no fear! You can make use of the "raw" gRPC API as well.

note

Make sure to configure your application to use the token you copied above. For example, for Python:

token = "t_your_token_here_1234567deadbeef"client = ArrakisClient(User, Document, access_token=token)

Working with the API#

Adding permissions checking#

Permissions checks in Authzed are accomplished via the Check API call.

After adding and configuring your client library, we can issue a Check call to check if a user has access to a sensitive resource:

Code Sample Parameter Values
Parameter NameValueDescription
Tenant SlugThe slug for your tenant
TokenYour token
Document IDThe ID of the document to check
User IDThe ID of the user against which to check
from arrakisclient.client import ArrakisClientfrom arrakisclient.types.namespace import ArrakisNamespace, Relationfrom arrakisclient.types.tuple import ArrakisUserset
class User(ArrakisNamespace):    __namespace__ = "someslug/user"    ellipsis = Relation(relation_name="...")
class Document(ArrakisNamespace):    __namespace__ = "someslug/document"    viewer = Relation(relation_name="viewer")    writer = Relation(relation_name="writer")
token = "t_my_token"client = ArrakisClient(User, Document, access_token=token)
a_object = Document("firstdoc")a_user = User("tom")
# Issue the Check.print(client.check(a_object.viewer, ArrakisUserset.from_onr(a_user.ellipsis)))

Granting permission to a user#

Now that we can lookup the permissions for a user with the Authzed API, the next step is to grant permissions to a user.

To do so, we create a Tuple to grant the user permission on the document:

Code Sample Parameter Values
Parameter NameValueDescription
Tenant SlugThe slug for your tenant
TokenYour token
Document IDThe ID of the document on which to grant permission
User IDThe ID of the user to grant permission
from arrakisclient.client import ArrakisClientfrom arrakisclient.types.namespace import ArrakisNamespace, Relationfrom arrakisclient.types.tuple import ArrakisUserset
class User(ArrakisNamespace):    __namespace__ = "someslug/user"    ellipsis = Relation(relation_name="...")
class Document(ArrakisNamespace):    __namespace__ = "someslug/document"    viewer = Relation(relation_name="viewer")    writer = Relation(relation_name="writer")
token = "t_my_token"client = ArrakisClient(User, Document, access_token=token)
a_object = Document("firstdoc")a_user = User("somegal")
# Issue the Check before adding permission.print(client.check(a_object.viewer, ArrakisUserset.from_onr(a_user.ellipsis)))
# Add permission for the user.with client.batch_write() as w:    w.create(a_object.reader(a_user))
# Issue the Check after adding permission.print(client.check(a_object.viewer, ArrakisUserset.from_onr(a_user.ellipsis), at_revision=w.revision))