What are API Tokens?

API tokens are token strings that can be generated for each Kintone App. API Tokens can be used to authenticate REST API calls instead of using password authentication. Although password authentication is an easy approach for calling REST APIs, it allows almost full access to any data within the Kintone environment. The usage of API Tokens limits the scope, as they can only be used for the App they are generated from. Permissions such as viewing and adding records can also be limited for each generated API Token.

How to Generate API Tokens

Each Kintone App created in the subdomain can generate API Tokens spcifically for that App. To generate new API Tokens, navigate to an App, and follow the Generating API Tokens article on the Kintone Help site.

How to Test API Tokens

The generated token can be tested by making a Kintone REST API call via curl. Run the curl command below, by replacing {API_Token}, {subdomain} and {AppID} with their respective values.

1

curl -H "X-Cybozu-API-Token: {API_Token}" "https://{subdomain}.kintone.com/k/v1/records.json?app={AppID}"

A list of records from the App should return in JSON format.

Troubleshooting

If the API Token authentication does not succeed, check the following points:

• Error: "The API token does not match the app" If this error is returned, check that the API Token is being used against the correct App ID. API Tokens generated from an App can only be used for that App.
• Error: "The specified API token does not match the API token generated via an app" If this error is returned, check that the API token string is copied correctly. Also check that the Update App button has been clicked for the App. Generated API Tokens cannot be used until the Update App button has been clicked.
• Error: "Using this API token, you cannot run the specified API" If this error is returned, check that the generated API Token has permissions to run the specified REST API. Permissions for API Tokens can be updated by accessing the API Token settings.
• HTML comes back If a bunch of HTML text is returned, check that the URL sent in the curl command is correct. This includes both checking the subdomain name and the REST API endpoint.

Limitations

• Not all Kintone APIs can use API Token authentication. The types of authentications that can be used are listed in each API document.
• API Tokens may be generated from Apps that contain Lookup fields and Related records fields. In this case, the API Tokens have limited access to these fields, as the data source belongs in a different App. This issue can be solved by generating an API Token from the data source App. 2 API Tokens can then be set in the header of the REST API call as described in the Requests with Multiple API Tokens article.