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. Details regarding this and other APIs affected by this change can be found here: API Updates for February 2023 (2nd Announcement).

MethodPUT
URLhttps://{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-Typeapplication/json

Contents

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.
Check here for more data on query formats. Some limitations exist when specifying the filter conditions.
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 REST API Request)

 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()