API Docs

User API Overview

Contents

The User API

The User API is a REST API that gets, adds and updates user/group/department information.

PROTOCOL FORMAT CHARACTER ENCODING ESCAPE SEQUENCE
HTTPS JSON UTF-8 Use \

User Authentication

The User REST API requires password authentication, with the appropriate Keys and Values set in the header of the request. If the Basic authentication security feature is also set on your domain, both headers for the Password Authentication and the Basic Authentication will be required for the request.

Password Authentication

Set X-Cybozu-Authorization on the request header, with a BASE64 encoded login name and password as the value.
If your log in name is "Kintone" and your password is "developer", BASE64 encode "Kintone:developer" and set it on the header as follows:

1

X-Cybozu-Authorization: S2ludG9uZTpkZXZlbG9wZXI=

Session Authentication

Session authentication is a method of authentication where a session ID is assigned to a user by the web server and saved as a cookie. This cookie is used to identify and authenticate the user. Session Authentication can only be used by JavaScript codes that are run on the pages of Kintone. CSRF tokens are necessary when using Session Authentication with POST／PUT／DELETE methods. Refer to the following documentation for more details on retrieving a CSRF token:
Get CSRF Token

Authentication Priority

The priority of authentication is as follows.

  1. Password authentication
  2. Session authentication

Basic Authentication (Legacy)

warning
Warning

As of June 2020, Basic Authentication has been deprecated, and is no longer available for use.

If your Kintone environment has set the Basic authentication security feature, add Authorization in the request header, with the string Basic and a BASE64 encoded login name and password of the Basic authentication as the value.
If the basic authentication log in name is "chocolate" and the basic authentication password is "pudding", place "Basic" in the value, followed by a BASE64 encoded "chocolate:pudding" as follows:

1

Authorization: Basic Y2hvY29sYXRlOnB1ZGRpbmc=

Request Headers

These request headers are used for the REST API.

HEADER REQUIRED VALUE
Host Required {subdomain}.kintone.com:443
Content-Type Conditional application/json.
Specify this only if the request body is in JSON format.
X-Cybozu-Authorization Conditional login_name:password encoded in Base64.
Only required when using Password Authentication.
For more information on Password Authentication, refer to the following documentation:
Password Authentication
Authorization Conditional Basic followed by a Base64 encoded login_name:password.
Only required when using deprecated Basic Authentication, which is no longer available as of June 2020.
For more information on Basic Authentication, refer to the following documentation:
Basic Authentication

Request URI

PURPOSE URI DETAILS
General https://{subdomain}.kintone.com/v1/{API_command}.json This is the general format for User APIs.

Responses

HTTP status code 200 denotes that the request was successful.
Treat any other status code as errors. Errors will respond with JSON data including the following information.

KEY VALUE
message The error message. The language of the message will differ depending on the user's language settings of the Kintone user used for the authentication.
id The ID of the error.
code The code of the error, to specify the type of error it is.

Sample Error Response 

1
2
3
4
5

{
  "message": "Invalid JSON string.",
  "id": "1505999166-897850006",
  "code": "CB_IJ01"
}

Notes

X-HTTP-Method-Override Header

  • Add the X-HTTP-Method-Override header to work around the Request URI Too Large error that occurs when the request URI exceeds 4KB. All User APIs support this header.
  • If a GET request of a User API is sent using the Kintone REST API Request method, and the URI length exceeds 4KB, the X-HTTP-Method-Override header will automatically be added and the request will be sent as a POST request. This allows User API requests with long URIs to be executed without errors.
    For more information on the Kintone REST API Request method, refer to the following link:
    Kintone REST API Request