Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sync REST: Permissions

Permissions bind an identity to an object with flags for reading, writing, and managing that object. Permissions do not have a SID or a unique path; they are identified by the Service, Object, and Token Identity specified in the URL. Permissions may be set and retrieved. Deletion is equivalent to setting all flags to false.

{   "read": true,
    "write": false,
    "manage": false
}

For an SDK:

  • read permission allows an endpoint (browser or mobile) to attach to the object, query individual items, and receive notification of any updates to that object made remotely.
  • write permission allows an endpoint to change data and (for Lists and Maps) add or remove items.
  • manage permission allows an endpoint to remove a Sync object from the system. You cannot give an SDK permissions to manipulate permissions.

Permissions only take effect if the ACLEnabled flag is set on your service instance. Your backend servers are always in "God Mode", having full access to all your account's Sync resources irrespective of configured Permissions or the ACLEnabled flag.

Setting or Updating Permissions

POST /v1/Services/:serviceSid/:ObjectType/:sidOrUniqueName/Permissions/:identity
Content-Type: x-www-form-encoded

For an existing Sync object, configures the permissions that apply to any SDKs authenticated with a matching identity specified in their Auth Token. If the ACLEnabled flag is unset or if the desire is to restrict all access for that identity, no explicit POST is needed.

This resource accepts x-www-form-encoded bodies. There are three form parameters, all of which are optional.

Parameter Description Value Domain Default Value
Read If set, allows SDK clients with a matching token identity to query this Sync object and/or true or false false
Write If set, allows SDK clients with a matching token identity to update data in Sync objects, and (in the case of Maps and Lists) add and remove items. true or false false
Manage If set, allows SDK clients with a matching token identity to remove Sync objects. true or false false

Example:

POST /v1/Services/ISxx/Maps/users/Permissions/administrator
Content-Type: x-www-form-encoded
Read=true&Write=true&Manage=false

Loading Code Sample...
      
      
          
          
          
          
        
      Loading Code Sample...
          
          
              
              
              
              
            
          Loading Code Sample...
              
              
                  
                  
                  
                  
                

              Fetching Permissions

              GET /v1/Services/:serviceSid/:ObjectType/:sidOrUniqueName/Permissions/:identity
              Accepts: application/json
              

              Retrieves the configured permission flags for this object/identity pair. The expected response is 200 OK.

              Loading Code Sample...
                  
                  
                      
                      
                      
                      
                    
                  Loading Code Sample...
                      
                      
                          
                          
                          
                          
                        
                      Loading Code Sample...
                          
                          
                              
                              
                              
                              
                            

                          Deleting Permissions

                          DELETE /v1/Services/:serviceSid/:ObjectType/:sidOrUniqueName/Permissions/:identity
                          

                          Equivalent to POST with all parameters false, this verb revokes all permissions to the resource from the provided token-identity. Success is indicated with the response 204 No Content.

                          Loading Code Sample...
                              
                              
                                  
                                  
                                  
                                  
                                
                              Loading Code Sample...
                                  
                                  
                                      
                                      
                                      
                                      
                                    
                                  Loading Code Sample...
                                      
                                      
                                          
                                          
                                          
                                          
                                        

                                      Listing Permissions for an Object

                                      GET /v1/Services/:serviceSid/:ObjectType/:sidOrUniqueName/Permissions
                                      Accepts: application/json
                                      

                                      Responds with a paged list (permissions) of any permissions applied to the target object. This will not include false/false/false permission tuples; not having a mapping is equivalent to having no permissions.

                                      Responses will arrive in the following format:

                                      {
                                        "permissions": [
                                          {
                                            "account_sid": "ACxx",
                                            "service_sid": "ISxx",
                                            "document_sid" | "list_sid" | "map_sid": "XXxx",
                                            "identity": "alice",
                                            "read": true,
                                            "write": false,
                                            "manage": false,
                                            "url": "https://sync.twilio.com/v1/Services/:serviceSid/Maps/:mapSid/Permissions/:identity"
                                          },
                                          ...
                                        ],
                                        "meta": {
                                          "next_page_url": "https://...",
                                          "previous_page_url": "https://..."
                                        }
                                      }
                                      
                                      Loading Code Sample...
                                          
                                          
                                              
                                              
                                              
                                              
                                            
                                          Loading Code Sample...
                                              
                                              
                                                  
                                                  
                                                  
                                                  
                                                
                                              Loading Code Sample...
                                                  
                                                  
                                                      
                                                      
                                                      
                                                      
                                                    

                                                  Need some help?

                                                  We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

                                                  Loading Code Sample...