This content originally appeared on DEV Community and was authored by Christy Jacob
Intro
#30DaysOfAppwrite is a month long event focused at giving developers a walkthrough of all of Appwrite's features, starting from the basics to more advanced features like Cloud Functions! Alongside we will also be building a fully featured Medium Clone to demonstrate how these concepts can be applied when building a real world app. We also have some exciting prizes for developers who follow along with us!
Teams API
Welcome to Day 13 ?. Today we'll go through the Teams API and understand how it allows us to easily manage permissions for groups of users. The main purpose of Teams API is to create groups of users and grant bulk permissions in an easy way. These permissions can then be used to control access to Appwrite's resources like documents and files in storage.
Let's say you have a text file that you would like to share with a group of friends. In that case, you can create a team and give different roles to the members of the team. ( view, edit, comment, owner etc.)
Team permissions in Appwrite use one the following syntaxes
-
team:[TEAM_ID]
This permission grants access to any member of the specific team. To gain access to this permission, the user must be the team creator (owner), or receive and accept an invitation to join this team.
-
member:[MEMBER_ID]
This permissions grants access to a specific member of a team. This permission will only be valid as long as the user is still an active member of the specific team. To view a user's member ID, fetch the team members list using the Get Team Memberships endpoint.
-
team:[TEAM_ID]/[ROLE]
This permission grants access to any member who possesses a specific role in a team. To gain access to this permission, the user must be a member of the specific team and have the given role assigned to him or her. Team roles can be assigned when inviting a user to become a team member.
ROLEcan be any string. However, theownerrole is created automatically when a new team is created from a Client SDK.
Let's take a few examples to make this more clear
| Permission | Description |
|---|---|
| team:abcd | Access to all members of team abcd |
| team:abc | Access to all members of team abc |
| member:abc | Access to a user with membershipId abc |
| team:abcd/owner | Access to members of team abcd who have the role owner. By default, only the creator of the team has this role. |
| team:abcd/viewer | Access to members of team abcd who have the role viewer. |
The teams API is accessible from both the Client and Server SDKs. We will cover how to create these teams and assign roles using both the Client and Server SDKs ?.
Gotchas
There are a few notable differences when you create a team from a Client SDK vs when you create a team using a Server SDK.
When a user creates a team using a Client SDK, they become the owner of the team and are automatically assigned the team:[TEAM_ID]/owner role.
When a team is created using a Server SDK using an API key, there is no logical owner of the team since API keys run in admin mode. In this case, the Server SDK should also create the first member of the team, and explicitly assign the owner permissions. We will cover these with an example.
Client SDK
This is where you can find the docs for the Client Teams API. Creating a team is really simple - all you need to do is think of a Really Cool Name.
let promise = sdk.teams.create('Really Cool Name');
promise.then(function (response) {
console.log(response); // Success
}, function (error) {
console.log(error); // Failure
});
This will create a team with the current user as the owner. You can verify this by heading to your Appwrite Console > Users > Teams > Really Cool Name
To add new members to this team, you can make use of the createMembership() function. Only owners of a team can add new members to the team. An email with a link to join the team will be sent to the new member's email address. If the member doesn't exist in the project, it will be created automatically.
Before this, ensure that you have SMTP setup on your Appwrite Server. We covered this in our previous tutorial on Day 11.
Let's say you would like to invite a new member ( email@example.com ) to your team and grant them two new roles in the team, namely : viewer and editor. You can do this using the following snippet. Use the 'URL' parameter to redirect the user from the invitation email back to your app. When the user is redirected, use the Update Team Membership Status endpoint to allow the user to accept the invitation to the team.
let promise = sdk.teams.createMembership('[TEAM_ID]', 'email@example.com', '', ['viewer', 'editor'], 'https://example.com/acceptTeamInvite');
promise.then(function (response) {
console.log(response); // Success
}, function (error) {
console.log(error); // Failure
});
When the user clicks on the team invitation email from their inbox, they will be redirected to https://example.com/acceptTeamInvite?teamId=xxx&inviteId=yyy&userId=zzz&secret=xyz . The four parameters can then be extracted from the query string and the updateMembershipStatus() method can be called to confirm membership to the team.
let promise = sdk.teams.updateMembershipStatus('[TEAM_ID]', '[INVITE_ID]', '[USER_ID]', '[SECRET]');
promise.then(function (response) {
console.log(response); // Success
}, function (error) {
console.log(error); // Failure
});
We will use this in practice in tomorrow's tutorial where we add support to invite users to a team in our blog app!
Server SDK
The server version of the function looks really similar to the client version but the key difference here is the usage of an API key with a teams.read and teams.write scopes. This function creates a team, but unlike the Client SDK, this team has no members yet.
const sdk = require('node-appwrite');
// Init SDK
let client = new sdk.Client();
let teams = new sdk.Teams(client);
client
.setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
.setProject('5df5acd0d48c2') // Your project ID
.setKey('919c2d18fb5d4...a2ae413da83346ad2') // Your secret API key
;
let promise = teams.create('Really Cool Team');
promise.then(function (response) {
console.log(response);
}, function (error) {
console.log(error);
});
We need to explicitly add members to this team using the Server version of createMembership(). The parameters here are exactly the same as the Client version.
const sdk = require('node-appwrite');
// Init SDK
let client = new sdk.Client();
let teams = new sdk.Teams(client);
client
.setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
.setProject('5df5acd0d48c2') // Your project ID
.setKey('919c2d18fb5d4...a2ae413da83346ad2') // Your secret API key
;
let promise = teams.createMembership('[TEAM_ID]', 'email@example.com', '', ['owner'], 'https://example.com/acceptTeamInvite');
promise.then(function (response) {
console.log(response);
}, function (error) {
console.log(error);
});
When a new member is added to the team from the Server, email verification is not required and hence no email will be sent in this case.
That's a wrap! You now know how to create and and new members to your team both from the client and the server. In the next article we will add this functionality to our demo app!
Credits
We hope you liked this write up. You can follow #30DaysOfAppwrite on Social Media to keep up with all of our posts. The complete event timeline can be found here
Feel free to reach out to us on Discord if you would like to learn more about Appwrite, Aliens or Unicorns ?. Stay tuned for tomorrow's article! Until then ?
This content originally appeared on DEV Community and was authored by Christy Jacob
Christy Jacob | Sciencx (2021-05-13T13:09:02+00:00) #30DaysOfAppwrite : Appwrite Teams. Retrieved from https://www.scien.cx/2021/05/13/30daysofappwrite-appwrite-teams/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.