review access control

Author: Francesca-Bit

docs/_sidebar.md

@@ -159,21 +159,21 @@
   - [first_commit](api/woqlLibrary.js?id=first_commit)
 - [AccessControl](api/accessControl.js?id=AccessControl)
   - [getDefaultOrganization](api/accessControl.js?id=getDefaultOrganization)
-  - [getAPIToken](api/accessControl.js?id=getAPIToken)
-  - [setAPIToken](api/accessControl.js?id=setAPIToken)
+  - [getJwtToken](api/accessControl.js?id=getJwtToken)
+  - [setJwtToken](api/accessControl.js?id=setJwtToken)
   - [getAPIUrl](api/accessControl.js?id=getAPIUrl)
-  - [getUserRoles](api/accessControl.js?id=getUserRoles)
+  - [getAccessRoles](api/accessControl.js?id=getAccessRoles)
   - [createOrganization](api/accessControl.js?id=createOrganization)
   - [ifOrganizationExists](api/accessControl.js?id=ifOrganizationExists)
-  - [removeUserFromOrg](api/accessControl.js?id=removeUserFromOrg)
   - [getPendingOrgInvites](api/accessControl.js?id=getPendingOrgInvites)
   - [sendOrgInvite](api/accessControl.js?id=sendOrgInvite)
   - [getOrgInvite](api/accessControl.js?id=getOrgInvite)
   - [deleteOrgInvite](api/accessControl.js?id=deleteOrgInvite)
   - [updateOrgInviteStatus](api/accessControl.js?id=updateOrgInviteStatus)
   - [getOrgUsers](api/accessControl.js?id=getOrgUsers)
+  - [removeUserFromOrg](api/accessControl.js?id=removeUserFromOrg)
   - [getDatabaseRolesOfUser](api/accessControl.js?id=getDatabaseRolesOfUser)
-  - [assignUserRole](api/accessControl.js?id=assignUserRole)
+  - [createUserRole](api/accessControl.js?id=createUserRole)
   - [updateUserRole](api/accessControl.js?id=updateUserRole)
 - [TypeDef](api/typedef.js?id=TypeDef)
   - [DocParamsGet](api/typedef.js?id=DocParamsGet)

docs/api/accessControl.js.md

@@ -6,6 +6,17 @@
 #### new AccessControl()
 The AccessControl object has various methods to control the access for users.
 
+**Example**  
+```js
+const accessContol = new AccessControl("https://servername.com",
+{organization:"my_team_name",
+jwt:"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkpXUjBIOXYyeTFORUd........"})
+accessControl.getOrgUsers().then(result=>{
+     console.log(result)
+})
+//if the jwt is expired you can change it with
+ accessControl.setJwtToken("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkpXUjBIOXYyeTFORUd.......")
+```
 
 ### getDefaultOrganization
 #### accessControl.getDefaultOrganization(params) ⇒ <code>string</code> \| <code>undefined</code>
@@ -18,25 +29,25 @@ Get a organization from parameters.
 | params | <code>object</code> | The parameters |
 
 
-### getAPIToken
-#### accessControl.getAPIToken(params) ⇒ <code>string</code>
+### getJwtToken
+#### accessControl.getJwtToken(params) ⇒ <code>string</code>
 Get a API token from parameters.
 
-**Returns**: <code>string</code> - apiToken  
+**Returns**: <code>string</code> - jwt api token  
 
 | Param | Type | Description |
 | --- | --- | --- |
 | params | <code>object</code> | The parameters |
 
 
-### setAPIToken
-#### accessControl.setAPIToken(token)
+### setJwtToken
+#### accessControl.setJwtToken(jwt)
 Sets the API token for the object
 
 
 | Param | Type | Description |
 | --- | --- | --- |
-| token | <code>string</code> | The api token to use |
+| jwt | <code>string</code> | The jwt api token to use |
 
 
 ### getAPIUrl
@@ -50,8 +61,8 @@ Get a API url from cloudAPIUrl
 | cloudAPIUrl | <code>string</code> | The base url for cloud |
 
 
-### getUserRoles
-#### accessControl.getUserRoles() ⇒ <code>Promise</code>
+### getAccessRoles
+#### accessControl.getAccessRoles() ⇒ <code>Promise</code>
 Get all the system database roles types.
 
 **Returns**: <code>Promise</code> - A promise that returns the call response object, or an Error if rejected.  
@@ -66,30 +77,24 @@ Any user can create their own organization.
 | --- | --- | --- |
 | orgName | <code>string</code> | The organization name to create |
 
+**Example**  
+```js
+accessControl.createOrganization("my_org_name").then(result=>{
+     console.log(result)
+})
+```
 
 ### ifOrganizationExists
 #### accessControl.ifOrganizationExists(orgName) ⇒ <code>Promise</code>
-Check if the organization exists.
+Check if the organization exists. it is a Head call .
 
-**Returns**: <code>Promise</code> - A promise that returns the call response object, or an Error if rejected.  
+**Returns**: <code>Promise</code> - A promise that returns the call status object,  200: if the organization exists and 404: if the organization does not exist  
 
 | Param | Type | Description |
 | --- | --- | --- |
 | orgName | <code>string</code> | The organization name to check if exists. |
 
 
-### removeUserFromOrg
-#### accessControl.removeUserFromOrg(userId, [orgName]) ⇒ <code>Promise</code>
-Remove an user from an organization, only an admin user can remove an user from an organization
-
-**Returns**: <code>Promise</code> - A promise that returns the call response object, or an Error if rejected.  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| userId | <code>string</code> | The if of the user to be removed. |
-| [orgName] | <code>string</code> | The organization name in which the user is to be removed. |
-
-
 ### getPendingOrgInvites
 #### accessControl.getPendingOrgInvites([orgName]) ⇒ <code>Promise</code>
 Get the pending invitations list.
@@ -100,6 +105,21 @@ Get the pending invitations list.
 | --- | --- | --- |
 | [orgName] | <code>string</code> | The organization name. |
 
+**Example**  
+```js
+const invitationList = accessControl.getPendingOrgInvites().then(result=>{
+   console.log(invitationList)
+
+})
+//this will return an array of invitations object like this
+//[{@id: "Organization/my_team_name/invitations/Invitation/7ad0c9eb82b6175bcda9c0dfc2ac51161ef5ba7cb0988d992c4bce82b3fa5d25"
+//      @type: "Invitation"
+//      creation_date: "2021-10-22T11:13:28.762Z"
+//      email_to: "[email protected]"
+//      invited_by: "User/auth0%7C6162f8ab33567406a6bee0c"
+//      role: "Role/dataReader"
+//      status: "needs_invite"}]
+```
 
 ### sendOrgInvite
 #### accessControl.sendOrgInvite(userEmail, role, [note], [orgName]) ⇒ <code>Promise</code>
@@ -110,10 +130,16 @@ Send a new invitation
 | Param | Type | Description |
 | --- | --- | --- |
 | userEmail | <code>string</code> | The email of user. |
-| role | <code>string</code> | The role for user. |
+| role | <code>string</code> | The role for user. (the document @id role like Role/collaborator) |
 | [note] | <code>string</code> | The note to send with the invitation. |
 | [orgName] | <code>string</code> | The organization name. |
 
+**Example**  
+```js
+accessControl.sendOrgInvite("[email protected]","Role/admin","please join my team").then(result=>{
+   console.log(result)
+})
+```
 
 ### getOrgInvite
 #### accessControl.getOrgInvite(inviteId, [orgName]) ⇒ <code>Promise</code>
@@ -126,6 +152,13 @@ Get the invitation info
 | inviteId | <code>string</code> | The invite id to retrieve. |
 | [orgName] | <code>string</code> | The organization name. |
 
+**Example**  
+```js
+const fullInviteId="Organization/my_team_name/invitations/Invitation/7ad0c9eb82b6175bcda9c0dfc2ac51161ef5ba7cb0988d992c4bce82b3fa5d25"
+accessControl.getOrgInvite(fullInviteId).then(result=>{
+ console.log(result)
+})
+```
 
 ### deleteOrgInvite
 #### accessControl.deleteOrgInvite(inviteId, [orgName]) ⇒ <code>Promise</code>
@@ -138,10 +171,20 @@ Delete an invitation
 | inviteId | <code>string</code> | The invite id to delete. |
 | [orgName] | <code>string</code> | The organization name. |
 
+**Example**  
+```js
+const fullInviteId="Organization/my_team_name/invitations/Invitation/7ad0c9eb82b6175bcda9c0dfc2ac51161ef5ba7cb0988d992c4bce82b3fa5d25"
+accessControl.deleteOrgInvite(fullInviteId).then(result=>{
+     console.log(result)
+})
+```
 
 ### updateOrgInviteStatus
 #### accessControl.updateOrgInviteStatus(inviteId, accepted, [orgName]) ⇒ <code>Promise</code>
-Accept /Reject invitation
+Accept /Reject invitation. if the invitation has been accepted we add the current user to the organization. 
+
+the only user that can accept this invitation is the user registered with the invitation email, 
+we indentify the user with the jwt token
 
 **Returns**: <code>Promise</code> - A promise that returns the call response object, or an Error if rejected.  
 
@@ -151,6 +194,13 @@ Accept /Reject invitation
 | accepted | <code>boolean</code> | The status of the invitation. |
 | [orgName] | <code>string</code> | The organization name. |
 
+**Example**  
+```js
+const fullInviteId="Organization/my_team_name/invitations/Invitation/7ad0c9eb82b6175bcda9c0dfc2ac51161ef5ba7cb0988d992c4bce82b3fa5d25"
+accessControl.updateOrgInviteStatus(fullInviteId,true).then(result=>{
+  console.log(result)
+})
+```
 
 ### getOrgUsers
 #### accessControl.getOrgUsers([orgName]) ⇒ <code>Promise</code>
@@ -162,6 +212,38 @@ Get all the organization's users and roles
 | --- | --- | --- |
 | [orgName] | <code>string</code> | The organization name. |
 
+**Example**  
+```js
+accessControl.getOrgUsers().then(result=>{
+ console.log(result)
+})
+
+//this function will return an array of capabilities with users and roles
+//[{capability: "Capability/3ea26e1d698821c570afe9cb4fe81a3......"
+//     email: {@type: "xsd:string", @value: "[email protected]"}
+//     picture: {@type: "xsd:string",…}
+//     role: "Role/dataReader"
+//     scope: "Organization/my_org_name"
+//     user: "User/auth0%7C613f5dnndjdjkTTT"}]
+```
+
+### removeUserFromOrg
+#### accessControl.removeUserFromOrg(userId, [orgName]) ⇒ <code>Promise</code>
+Remove an user from an organization, only an admin user can remove an user from an organization
+
+**Returns**: <code>Promise</code> - A promise that returns the call response object, or an Error if rejected.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| userId | <code>string</code> | The id of the user to be removed. (this is the document user's @id) |
+| [orgName] | <code>string</code> | The organization name in which the user is to be removed. |
+
+**Example**  
+```js
+accessControl.removeUserFromOrg("User/auth0%7C613f5dnndjdjkTTT","my_org_name").then(result=>{
+ console.log(result)
+})
+```
 
 ### getDatabaseRolesOfUser
 #### accessControl.getDatabaseRolesOfUser(userId, [orgName]) ⇒ <code>Promise</code>
@@ -174,10 +256,31 @@ Get the user's role for every databases under the organization
 | userId | <code>string</code> | The user's id. |
 | [orgName] | <code>string</code> | The organization name. |
 
-
-### assignUserRole
-#### accessControl.assignUserRole(userId, scope, role, [orgName]) ⇒ <code>Promise</code>
-Assign user's a role for a resource (organization/database)
+**Example**  
+```js
+accessControl.getDatabaseRolesOfUser('User/auth0%7C61790e366377Yu6596a').then(result=>{
+     console.log(result)
+})
+
+//this is a capabilities list of databases and roles
+//[ {capability: "Capability/b395e8523d509dec6b33aefc9baed3b2e2bfadbd4c79d4ff9b20dce2b14e2edc" 
+//if there is an id we have a user specific capabality for this database
+   // name: {@type: "xsd:string", @value: "profiles_test"}
+   // role: "Role/dataUpdater"
+   // scope: "UserDatabase/7ebdfae5a02bc7e8f6d79sjjjsa4e179b1df9d4576a3b1d2e5ff3b4859"
+   // user: "User/auth0%7C61790e11a3966d006906596a"},
+
+//{ capability: null 
+// if the capability id is null the user level of access for this database is the same of the team
+  //name: {@type: "xsd:string", @value: "Collab002"}
+  //role: "Role/dataReader"
+  // scope: "UserDatabase/acfcc2db02b83792sssb15239ccdf586fc5b176846ffe4878b1aea6a36c8f"
+  //user: "User/auth0%7C61790e11a3966d006906596a"}]  
+```
+
+### createUserRole
+#### accessControl.createUserRole(userId, scope, role, [orgName]) ⇒ <code>Promise</code>
+Create a user's a role for a resource (organization/database)
 
 **Returns**: <code>Promise</code> - A promise that returns the call response object, or an Error if rejected.  
 
@@ -188,6 +291,14 @@ Assign user's a role for a resource (organization/database)
 | role | <code>string</code> | The user role to be assigned. |
 | [orgName] | <code>string</code> | The organization name. |
 
+**Example**  
+```js
+const dbId = "UserDatabase/acfcc2db02b83792sssb15239ccdf586fc5b176846ffe4878b1aea6a36c8f"
+accessControl.assignUserRole('User/auth0%7C61790e11a3966d006906596a',dbId,"Role/collaborator").then(result=>{
+     console.log(result)
+
+})
+```
 
 ### updateUserRole
 #### accessControl.updateUserRole(userId, capabilityId, scope, role, [orgName]) ⇒ <code>Promise</code>
@@ -203,3 +314,12 @@ Update user's a role for a resource (organization/database)
 | role | <code>string</code> | The user role to be updated. |
 | [orgName] | <code>string</code> | The organization name. |
 
+**Example**  
+```js
+const dbId = "UserDatabase/acfcc2db02b83792sssb15239ccdf586fc5b176846ffe4878b1aea6a36c8f"
+const capId= "Capability/b395e8523d509dec6b33aefc9baed3b2e2bfadbd4c79d4ff9b20dce2b14e2edc"
+accessControl.updateUserRole('User/auth0%7C61790e11a3966d006906596a',capId,dbId,"Role/dataUpdater").then(result=>{
+     console.log(result)
+
+})
+```