Update Field Permissions

Updates the Field 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 fields in an App are changed, the updated settings will be applied to the concerned fields 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/field/acl.json
URL(guest space)https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/field/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/field/acl.json
URL(guest space) https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/preview/field/acl.json

Permissions

  • App management permissions are needed.

Request Parameters

Parameters that are ignored will not be updated.

Parameter Value Required Description
app Integer or String Yes The App ID.
rights Array Yes An array listing data of field permissions. List in order of priority.
rights[].code String Yes The field code of the field to set permissions around.
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[].accessibility String Yes The permission to grant to the entity.
  • READ: Permissions to view only.
  • WRITE: Permissions to view and edit.
  • NONE: No permissions to view and edit
rights[].entities[].entity Object Yes An object containing data of the entity the permission is granted to.
rights[].entities[].entity.type String Yes The type of the entity the permission is granted to.
  • USER: User
  • GROUP: Group
  • ORGANIZATION: Department
  • FIELD_ENTITY: User field
rights[].entities[].entity.code String Yes The code of the entity the permission is 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[].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
38
39
40
41
42
43
44
45
var body = {
  'app': 1,
  'rights': [
    {
      'code': 'Text__single_line_',
      'entities': [
        {
          'accessibility': 'WRITE',
          'entity': {
            'type': 'USER',
            'code': 'user1'
          }
        },
        {
          'accessibility': 'READ',
          'entity': {
            'type': 'GROUP',
            'code': 'group1'
          }
        }
      ]
    },
    {
      'code': 'Number',
      'entities': [
        {
          'accessibility': 'NONE',
          'entity': {
            'type': 'ORGANIZATION',
            'code': 'org1'
          },
          'includeSubs': true
        }
      ]
    }
  ]
};

kintone.api(kintone.api.url('/k/v1/field/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
48
49
50
51
52
53
54
55
var body = {
  'app': 1,
  'rights': [
    {
      'code': 'Text__single_line_',
      'entities': [
        {
          'accessibility': 'WRITE',
          'entity': {
            'type': 'USER',
            'code': 'user1'
          }
        },
        {
          'accessibility': 'READ',
          'entity': {
            'type': 'GROUP',
            'code': 'group1'
          }
        }
      ]
    },
    {
      'code': 'Number',
      'entities': [
        {
          'accessibility': 'NONE',
          'entity': {
            'type': 'ORGANIZATION',
            'code': 'org1'
          },
          'includeSubs': true
        }
      ]
    }
  ],
  // CSRF TOKEN: used for all APIs that have an HTTP method of POST, PUT and DELETE on Kintone.
  '__REQUEST_TOKEN__': '566e8e7b-764a-40cf-b028-5daa6b94b9b7'
};

var url = 'https://{subdomain}.kintone.com/k/v1/field/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"
}