Example: Sharing an Application with other Users


This is a demonstration of how to share your namespace, or parts of your namespace, with other users. We do this using the Share object.

To understand more about what Shares are, we suggest starting with the Share Object Overview.

A Brief Recap


There are many reasons why you might want to Share parts of your namespace with other users. For example:

  • To build a large application which many users might work on
  • To make available a data-source which others can use and remix in their own applications

Shares allow you to make available all or parts of your namespace to other users. You can control the permissions for each Path and / or User. Shares are accountable - you always know who has written data to your namespace, and Shares can be revoked at any time.

Shares can be granted to an individual Identity, or a Group of identities

Creating a new Group


In our example, we will give access to a Group of users who can all contribute to our application. You could alternatively assign a Share to an individual user.

The current application looks like this:

FLOW: /alice/smart-tv/
FLOW: /alice/smart-tv/scheduling
FLOW: /alice/smart-tv/maintenance
FLOW: /alice/smart-tv/social
FLOW: /alice/smart-tv/system

We first create a Group for the Maintenance department:

curl https://api.flowthings.io/v0.1/alice/group/ \
    -H "X-Auth-Token: IlmK7uLSzQvXruJbyGMCfrcU05p52NXp" \
    -H "Content-Type: application/json" \
    -d '{
            "memberIds" : ["i54932047d4c67eee1cbdbd39", "i54a1d6b0d4c64b32178d8bd8"],
            "description" : "Maintenance Dept."
        }'

## Response:
{
    "head": {
        "status":201,
        "ok":true,
        "messages":["Your request has been processed successfully. A new resource has been created."],
        "errors":[],
        "references":{}
    },
    "body": {
        "id":"g54a334a9d4c65af20a9cb546",
        <...snip...>
    }
}

Note: We can use the Identity API to retrieve Identity ids for each user we want to add to the Group.

The API responded with a success, and gave us a Group ID of g54a334a9d4c65af20a9cb546. We'll need that when creating the Share.

Creating a Share

-- A Group on its own does nothing - it is merely a logical grouping of users to which we can assign Shares. Let's do that:

curl https://api.flowthings.io/v0.1/alice/share/ \
    -H "X-Auth-Token: IlmK7uLSzQvXruJbyGMCfrcU05p52NXp" \
    -H "Content-Type: application/json" \
    -d '{
            "issuedTo" : "g54a334a9d4c65af20a9cb546",
            "paths" : {
                "/alice/smart-tv/maintenance" : {
                    "read" : true,
                    "write" : true,
                    "dropRead" : true,
                    "dropWrite" : true
                },
                "/alice/smart-tv/system" : {
                    "read" : true,
                    "write" : false,
                    "dropRead" : true,
                    "dropWrite" : false
                }
            }
        }'

## Response:
{
    "head": {
        "status":201,
        "ok":true,
        "messages":["Your request has been processed successfully. A new resource has been created."],
        "errors":[],
        "references":{}
    },
    "body": {
        "id":"s54a33626d4c65af20a9cb54b",
        <...snip...>
    }
}

We've now generated a Share, and each of the Identities within the Maintenance department will receive a notification of the new access rights they have.

The Share spec contains a map of paths and the access writes for each. In our example above, we've given full access to all Paths at or below /alice/smart-tv/maintenance. We've also given restricted, read-only access to /alice/smart-tv/system and below.

Let's begin!


Now our Maintenance department can use their accounts to make changes to our application:

curl https://api.flowthings.io/v0.1/bob/flow \
    -H "X-Auth-Token: no7GsNL0pfmegatVuRJbXd3NMVBk6nQ4"  \
    -d '{ "path" : "/alice/smart-tv/maintenance/reports" }'

(responds OK)

If this user attempts to break out of the sandbox, they will be denied:

curl https://api.flowthings.io/v0.1/bob/flow \
    -H "X-Auth-Token: no7GsNL0pfmegatVuRJbXd3NMVBk6nQ4"  \
    -d '{ "path" : "/alice/smart-tv/dangerous" }'

## Response:
{
    "head":{
        "status":403,
        "ok":false,
        "messages":[],
        "errors":["Access to the requested resource is forbidden.Cannot CREATE Flow with actor(54932047d4c67eee1cbdbd31)"],
        "references":{}
    },
    "body":{}
}

Revoking Access


If for whatever reason, you wish to revoke access from a user, we can do the following:

  • Remove the user from the Group, OR
  • Delete the Share object (this will revoke access from the entire Group)

E.g. to delete the Share object:

curl https://api.flowthings.io/v0.1/alice/share/s54a33626d4c65af20a9cb54b \
    -H "X-Auth-Token: IlmK7uLSzQvXruJbyGMCfrcU05p52NXp" \
    -H "Content-Type: application/json" \
    -X DELETE

Notifications

Whenever another user makes a change to your Application, you will be sent a Notification to your Inbox Flow.