Update Record Permissions

Updates the Record permission settings of an App.
All settings of the pre-live App (not just the permission settings) will be deployed to the live App by using this API.

When the permissions settings of records in an App are changed, the updated settings will be applied to the concerned records sequentially in order of completion.

Method	PUT
URL	https://{subdomain}.kintone.com/k/v1/record/acl.json
URL(guest space)	https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/record/acl.json
Authentication	Password Authentication , API Token Authentication , Session Authentication
Content-Type	application/json

Pre-live settings
Permissions
Request Parameters
Sample Request
Response Parameters
Sample Response
Limitations

Pre-live settings

Apps may hold pre-live settings that have not yet been deployed to the live App.
Access the pre-live settings with the below URL.

URL	https://{subdomain}.kintone.com/k/v1/preview/record/acl.json
URL(guest space)	https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/preview/record/acl.json

Permissions

App management permissions are needed.

Request Parameters

Parameters that are ignored will not be updated.
If you grant an entity permission to edit or delete records, the entity must also be granted to have permission to view records.

Parameter	Value	Required	Description
app	Integer or String	Yes	The App ID.
rights	Array	Yes	An array listing data of record permissions. List in order of priority.
rights[].filterCond	String		The filter condition in a query format. For more information on query formats refer to the following article: Query String For more information on the limitations regarding filter conditions, refer to the following section: Limitations If this parameter is ignored, the filter condition will be "All records".
rights[].entities	Array	Yes	An array listing the entities the permissions are granted to. List in order of priority. The "Everyone" group will be treated with the lowest priority, wherever it is placed in the list.
rights[].entities[].entity	Object	Yes	An object containing data of the entity the permissions are granted to.
rights[].entities[].entity.type	String	Yes	The type of the entity the permissions are granted to. USER: User GROUP: Group ORGANIZATION: Department FIELD_ENTITY: User field
rights[].entities[].entity.code	String	Yes	The code of the entity the permissions are granted to. If the "Everyone" group is not specified, the "Everyone" group will have no permissions to view/edit/delete. To specify guest space users, add the string "guest/" before the guest's log in name.
rights[].entities[].viewable	Boolean or String		The view permission of the entity. `true`: Grant view permission `false`: Deny view permission If ignored, the value is false.
rights[].entities[].editable	Boolean or String		The edit permission of the entity. `true`: Grant edit permission `false`: Deny edit permission If ignored, this value is false. If the entity has no permission to view the record, this value is false.
rights[].entities[].deletable	Boolean or String		The delete permission of the entity. `true`: Grant delete permission `false`: Deny delete permission If ignored, this value is false. If the entity has no permission to view the record, this value is false.
rights[].entities[].includeSubs	Boolean or String		The permission inheritance settings of the department the permissions are granted to. `true`: Permissions are inherited. `false`: Permissions are not inherited. If ignored, this value is false.
revision	Integer or String		Specify the revision number of the settings that will be deployed. The request will fail if the revision number is not the latest revision. The revision will not be checked if this parameter is ignored, or -1 is specified.

Sample Request

JavaScript using kintone.api()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


var body = {
  'app': 1,
  'rights': [
    {
      'filterCond': 'Updated_datetime > "2012-02-03T09:00:00Z" and Updated_datetime < "2012-02-03T10:00:00Z"',
      'entities': [
        {
          'entity': {
            'type': 'ORGANIZATION',
            'code': 'org1'
          },
          'viewable': false,
          'editable': false,
          'deletable': false,
          'includeSubs': true
        },
        {
          'entity': {
            'type': 'FIELD_ENTITY',
            'code': 'Updated_by'
          },
          'viewable': true,
          'editable': true,
          'deletable': true
        }
      ]
    }
  ]
};

kintone.api(kintone.api.url('/k/v1/record/acl.json', true), 'PUT', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

XMLHttpRequest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47


var body = {
  'app': 1,
  'rights': [
    {
      'filterCond': 'Updated_datetime > "2012-02-03T09:00:00Z" and Updated_datetime < "2012-02-03T10:00:00Z"',
      'entities': [
        {
          'entity': {
            'type': 'ORGANIZATION',
            'code': 'org1'
          },
          'viewable': false,
          'editable': false,
          'deletable': false,
          'includeSubs': true
        },
        {
          'entity': {
            'type': 'FIELD_ENTITY',
            'code': 'Updated_by'
          },
          'viewable': true,
          'editable': true,
          'deletable': true
        }
      ]
    }
  ],
  // CSRF TOKEN: used for all APIs that have an HTTP method of POST, PUT and DELETE on Kintone.
  '__REQUEST_TOKEN__': kintone.getRequestToken()
};

var url = 'https://{subdomain}.kintone.com/k/v1/record/acl.json';
var xhr = new XMLHttpRequest();
xhr.open('PUT', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onload = function() {
  if (xhr.status === 200) {
    // success
    console.log(JSON.parse(xhr.responseText));
  } else {
    // error
    console.log(JSON.parse(xhr.responseText));
  }
};
xhr.send(JSON.stringify(body));

Response Parameters

Parameter	Type	Description
revision	String	The revision number of the App settings.

Sample Response

1
2
3


{
  "revision": "3"
}

Limitations

The parameters that can be set in rights[].filterCond are the same as the conditions you can set on the GUI.
The following limitations apply:

"order by", "limit", and "offset" cannot be used.
"and" and "or" cannot be used in conjunction.
"like" and "not like" cannot be used for the following fields:
- Text
- Link
"in", ">", and <" cannot be used for the following fields:
- Record number
- Number
- Calculated
"=" cannot be used for the following fields:
- Status
The following fields cannot be included in the condition:
- Text Area
- Rich text
- Attachment
The following functions cannot be used:
- NOW()
- TODAY()
- YESTERDAY()
- TOMORROW()
- THIS_WEEK()
- LAST_WEEK()
- NEXT_WEEK()
- LAST_MONTH()
- NEXT_MONTH()
- THIS_MONTH()
- THIS_YEAR()
- LAST_YEAR()
- NEXT_YEAR()

API Docs