Overview

When using the REST APIs, an authorization header will be required. There are two main ways to authenticate when using REST APIs. Using password authentication allows the use of REST APIs with user-level permission, meaning that the authenticated user will need to have permission to control the App or space for the API to succeed. The other option is using API tokens to manipulate Apps with REST APIs. Each App in Kintone can create API tokens that will work specifically with that App. Other authentication methods, session authentication and OAuth authentication will also be briefly discussed.

Password authentication

X-Cybozu-Authorization is placed in the request header with a BASE64 encoded login name and password. BASE64 encode is done in the following format: Log_in_name:password.

For example, for a login name of "kintone" and a password of "developer", BASE64 encode "kintone:developer" and add this to the header:

1

X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=

API token authentication

Each App in Kintone can generate API tokens through the Advanced Settings in the App's settings menu. Refer to the Generating an API Token article from the Kintone Help for information on generating API tokens from an App.

X-Cybozu-API-Token is placed in the request header with the API Token. If the generated API token of the app is "9wOomr3kpP9d1JS34Uyz72xqQ1pLI4PkcziRFTuZ", add the following to the header:

1

X-Cybozu-API-Token: 9wOomr3kpP9d1JS34Uyz72xqQ1pLI4PkcziRFTuZ

Multiple API Tokens may be used in the case of performing REST API operations involving Lookup fields or Related Record fields. Specify the API Tokens in the header like so, with a comma in between:

1

X-Cybozu-API-Token: 9wOomr3kpP9d1JS34Uyz72xqQ1pLI4PkcziRFTuZ,D27Dss1udL2iZtiKMniN0s30goy8gtnnEjn8Z2Ou

The same effect may also be achieved by writing the API Tokens in two separate headers.

• Each App can generate up to 20 API Tokens.
• REST APIs initiated with API Tokens will be recorded in Kintone as operations done by the user named Administrator.
• Note that the X-Cybozu-Authorization header will be prioritized over this authentication.
• API Token authentication is applicable for the following Kintone REST APIs:
  • Record
    • Get Record / Add Record / Update Record
      (To create/update values of Lookup fields, place multiple API Tokens in the header )
    • Get Records / Add Records / Update Records / Delete Records
    • Get Cursor / Add Cursor / Delete Cursor
    • Get Comments / Add Comment / Delete Comment
    • Bulk Request
    • Update Status
    • Update Statuses
    • Update Assignees
  • Files
    • Download File / Upload File
  • Apps
    • Get App
    • Get Form Fields / Add Form Fields / Update Form Fields / Delete Form Fields
    • Get Form Layout / Update Form Layout
    • Get Views / Update Views (for Apps with no Custom Views)
    • Get General Settings / Update General Settings
    • Get Process Management Settings / Update Process Management Settings
    • Deploy App Settings
    • Get App Deploy Status
    • Get General Notification Settings / Update General Notification Settings
    • Get Per Record Notification Settings / Update Per Record Notification Settings
    • Get Reminder Notification Settings / Update Reminder Notification Settings
    • Get App Permissions / Update App Permissions
    • Get Record Permissions / Update Record Permissions
    • Get Field Permissions / Update Field Permissions
    • Get Graph Settings / Update Graph Settings
    • Get Action Settings / Update Action Settings
    • Get Form
• Enabling department access control will prevent everyone but Kintone Administrators from creating and viewing API Tokens. Refer to Using Department Access Control from the Kintone Help for more information on department access control.

OAuth Client authentication

OAuth 2.0 can be used to authenticate applications that lie outside of Kintone to run Kintone API requests. OAuth 2.0 provides a secure way for your application to access Kintone data, as it does not require users to store their Kintone user and passwords on the application.

For more information, please refer to the How to Add OAuth Clients article.

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 Get CSRF Token documentation for more details on retrieving a CSRF token.

Authentication priority

The priority of authentication is as follows.

1. Password authentication
2. API Token authentication
3. OAuth Client authentication
4. Session authentication

Guest users running API calls will only be able to use session authentication. They cannot use password authentication.

SAML Environments

Security Assertion Markup Language (SAML) is an authentication option that allows for Kintone login via a company's Identity Provider (IdP). The SAML redirect can be bypassed by placing saml=off in the parameter of the login URL. This bypassing method can be restricted to only the Users & System Administrators , if the "Require SAML authentication" checkbox is checked in the SAML Authentication settings. Checking this checkbox also restricts access of API calls from certain types of authentications:

• Subdomains with the "Require SAML authentication" checkbox unchecked:
  APIs may be authenticated via Password Authentication
  APIs may be authenticated via API Token Authentication
  APIs may be authenticated via OAuth
• Subdomains with the "Require SAML authentication" checkbox checked:
  APIs may be authenticated via Password Authentication but limited to only User and System Administrators
  APIs may be authenticated via API Token Authentication
  APIs may be authenticated via OAuth

For step-by-step instructions on enabling the SAML Authentication feature, refer to the Requiring Users to Login Through SAML Authentication Kintone Help Center article.

Basic authentication (Legacy)

Warning

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

Kintone environments using basic authentication will need an additional authorization header. Add "Basic" followed by a BASE64 encoded "Basic_log_in_name:Password". Note that initiating REST APIs for Apps in guest spaces will not need a header for basic authentication, as basic authentication itself cannot be used for guest spaces. If the basic authentication login name is "chocolate" and the password is "pudding", BASE64 encode "chocolate:pudding" and add this to the header:

1

Authorization:Basic Y2hvY29sYXRlOnB1ZGRpbmc=