{"_id":"56ca81146b58fb0b00c6d2fc","__v":2,"project":"56bc8e679afb8b0d00d62dcf","version":{"_id":"56bc8e689afb8b0d00d62dd2","project":"56bc8e679afb8b0d00d62dcf","__v":18,"createdAt":"2016-02-11T13:36:40.146Z","releaseDate":"2016-02-11T13:36:40.146Z","categories":["56bc8e689afb8b0d00d62dd3","56c3c837bc41330d009f25ed","56c3c83e521f350d00d348eb","56c3c8452d97560d00e23cd8","56c3c85234df460d00c2beb8","56c4180d70187b17005f43b4","56c418162d97560d00e23cf6","56c4181cc4796b0d007ef039","56c4182370187b17005f43b5","56c418292e75e01700986052","56c4183328bd680d005e7ac6","56c4183bbb64720d00552b88","56c418414040602b0064cea0","56c4184754b6030d00ec29a1","56c4184c28bd680d005e7ac7","56c4185370187b17005f43b6","56c4185b6063071700500cfc","582a98b6f8c0a0190053d7a5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"56c4180d70187b17005f43b4","__v":5,"project":"56bc8e679afb8b0d00d62dcf","version":"56bc8e689afb8b0d00d62dd2","pages":["56c418c854b6030d00ec29a2","56c418e670187b17005f43b7","56c418efc4796b0d007ef03a","56c418f94040602b0064cea1","56ca81146b58fb0b00c6d2fc"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-17T06:49:49.187Z","from_sync":false,"order":1,"slug":"buddy-basics","title":"Buddy Basics"},"githubsync":"","parentDoc":null,"user":"56b98db7bb36440d0001f492","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-22T03:31:32.930Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"### Permission Scopes\n\nBuddy supports two permissions scopes:\n\n* `app`: Any app user has the access in question\n* `user`: Only the owning user has access\n\n### Permissions on Objects\n\nMost Buddy objects support two types of standard permissions, available as parameters on the object's _create_ or _update_ operation:\n\n* `readPermissions`\n* `writePermissions`\n\n This allows your application to create objects that can be seen or modified either by any app user or just by the user that created the object. \n\n**Note:** In all cases _only the user that created an object can delete it_.\n\nObject owners can also grant read or write permissions to specific users, also known as sharing, see below for details.\n\n### [](#sharing)Sharing with Other Users\n\nBuddy also supports the ability to grant read or write permissions to a specific user via the `sharing` APIs.\n\nFor each Buddy object type, there is a `sharing` route that supports setting or clearing permissions for another user ID.  This operation can only be called by the owner of the object.\n\nThe general format is:\n\n     PUT /[object type]/[object ID]/sharing/[user ID]\n         {\n            permissions: '[permissions]'\n         }\n\nWhere:\n\n* **object type**: The type of object such as `blobs`, `users`, `checkins`, etc.\n* **object ID**: The ID of the object to set permissions on\n* **user ID**: The ID of the user to grant permissions to\n* **permissions**: The permissions to set as `Read`, `Write`, `Read,Write`, or `None`\n\nNote that permissions `None` is equivalent to:\n\n    DELETE /[object type]/[object ID]/sharing/[user ID]\n\n\nAs an example, if there is a picture with ID `pic1234`, with `User` permissions, only the owning user can view or modify it. But the owner would like to make the picture visible to another user, say a user with the ID `user5678`.\n\n    PUT /pictures/pic1234/sharing/user5678\n       { \n         permissions: 'Read'\n       }\n\nNow, user `user5678` will be able to successfully call:\n\n    GET /pictures/pic1234\n\n#### Setting Bulk Permissions\n\nYou can also set permissions for more than one user at a time, using the following call:\n\n    POST /pictures/pic1234/sharing\n      {\n        userIds: ['user5678', 'user8765'],\n        permissions: 'Read,Write'\n      }\n\n\n\n### Metadata Visibility\n\nFor Buddy's [Metadata](doc:metadata), the same `app` or `user` values are available via a parameter called `visibility`.  \n\nThis works similarly to object permissions but is for both read and write.  However, the difference is that `user` visibility means that the value is available per-user.  In other words every user in your app can add the same metadata key and they will not conflict.  \n\nFor example, each user could specify their own category on a picture, and the metadata system would make this possible.  Conversely, if you wanted any user to be able to \"like\" a photo, such that the count of likes is viewable by all users, you could use an `app` visibility metadata value.","excerpt":"","slug":"access-permissions","type":"basic","title":"Access Permissions"}

Access Permissions


### Permission Scopes Buddy supports two permissions scopes: * `app`: Any app user has the access in question * `user`: Only the owning user has access ### Permissions on Objects Most Buddy objects support two types of standard permissions, available as parameters on the object's _create_ or _update_ operation: * `readPermissions` * `writePermissions` This allows your application to create objects that can be seen or modified either by any app user or just by the user that created the object. **Note:** In all cases _only the user that created an object can delete it_. Object owners can also grant read or write permissions to specific users, also known as sharing, see below for details. ### [](#sharing)Sharing with Other Users Buddy also supports the ability to grant read or write permissions to a specific user via the `sharing` APIs. For each Buddy object type, there is a `sharing` route that supports setting or clearing permissions for another user ID. This operation can only be called by the owner of the object. The general format is: PUT /[object type]/[object ID]/sharing/[user ID] { permissions: '[permissions]' } Where: * **object type**: The type of object such as `blobs`, `users`, `checkins`, etc. * **object ID**: The ID of the object to set permissions on * **user ID**: The ID of the user to grant permissions to * **permissions**: The permissions to set as `Read`, `Write`, `Read,Write`, or `None` Note that permissions `None` is equivalent to: DELETE /[object type]/[object ID]/sharing/[user ID] As an example, if there is a picture with ID `pic1234`, with `User` permissions, only the owning user can view or modify it. But the owner would like to make the picture visible to another user, say a user with the ID `user5678`. PUT /pictures/pic1234/sharing/user5678 { permissions: 'Read' } Now, user `user5678` will be able to successfully call: GET /pictures/pic1234 #### Setting Bulk Permissions You can also set permissions for more than one user at a time, using the following call: POST /pictures/pic1234/sharing { userIds: ['user5678', 'user8765'], permissions: 'Read,Write' } ### Metadata Visibility For Buddy's [Metadata](doc:metadata), the same `app` or `user` values are available via a parameter called `visibility`. This works similarly to object permissions but is for both read and write. However, the difference is that `user` visibility means that the value is available per-user. In other words every user in your app can add the same metadata key and they will not conflict. For example, each user could specify their own category on a picture, and the metadata system would make this possible. Conversely, if you wanted any user to be able to "like" a photo, such that the count of likes is viewable by all users, you could use an `app` visibility metadata value.