API Docs

How to Add OAuth Clients

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.

To use OAuth 2.0 with Kintone, you must first register your application with Kintone. Your application will need to support the OAuth authorization flow to obtain the access token that can be used to run Kintone's APIs.

For more information on OAuth 2.0, refer to the official site: OAuth 2.0 (External link)

Contents

Register Your Application to Kintone

Your application must first be registered to Kintone through the Integration settings to generate the OAuth credentials. Follow the steps below to register your application:

  1. Log into Kintone, click the gear icon on the upper right menu of Kintone and navigate to the User & System Administration page.

  2. Click on OAuth under System Administration.

  3. Click on the green Add OAuth Client button under Set up Advanced Services.

  4. Enter in the details of the OAuth client.

    • Client name (required): The name of the application. Users will view this name when they are asked to grant access to your application.
    • Client logo (optional): The logo of the application. Users will view this logo when they are asked to grant access to your application.
    • Redirect endpoint (required): The URL where kintone.com will redirect the user to after granting access to the application.

  5. Clicking Save will add the client, and the following information will be automatically generated:

    • Client ID: A unique ID that is created when your application is registered to kintone.com.
    • Client secret: A secret value that is created when your application is registered to kintone.com.
    • Authorization endpoint: The URL of the OAuth authorization endpoint.
    • Token endpoint: The URL of the OAuth token endpoint.

  6. Click on Configure users next to the added client, to set which users in your Kintone domain have permission to interact with the client. When the client is initially registered to kintone.com, by default, no users are able to interact with the application until they are given permission through this setting.

  7. From the Configure Users settings screen, choose which users will be able to interact with the client to process the OAuth flow and click save. The OAuth client will only be enabled for those who are selected with the check box in this setting.

    Be aware that when a new user is created in Kintone, the check box for the new user is unchecked by default, and the OAuth client is disabled for the user.

Implementing the OAuth Authorization Framework to Your Application

kintone.com uses Authorization Code Grants for the OAuth process flow.

Authorization code grant flow

The steps necessary for running a Kintone API are as follows:

  1. Authorization request
  2. User approval
  3. Authorization code retrieval
  4. Access token request
  5. API Execution

The next steps show an example of running each OAuth protocol API type using curl.

1. Authorization request

The following URL is accessed in order to request authorization as the client from the user. As an example, k:app_record:read is specified in the scope.

1
2

https://{subdomain}.kintone.com/oauth2/authorization
?client_id={your_client_id}&redirect_uri={your_redirect_url}&state=state1&response_type=code&scope=k%3Aapp_record%3Aread

The details of the parameters are as follows:

Parameter Required Description
client_id Yes The unique client ID.
redirect_uri Yes The redirect endpoint. Make sure to encode the URL.
state Yes A random value in order to prevent CSRF as is defined in the OAuth 2.0
specifications. In this example, the value "state1" is specified.
response_type Yes Specify code.
scope Yes The scope. Refer to the following article for more details on the scope:
OAuth Permission Scopes
When specifying multiple scopes, each scope must be separated by a comma.

2. User approval

On the following page that appears, click Allow to approve the authorization request.

The user will be navigated to the Redirect Endpoint URL, specified in Step 4 of the following section:
Register your application to Kintone

3. Authorization code retrieval

When the authorization is approved, the browser accesses the redirect URL. The state parameter and the code parameter are added to the URL. Treat the code parameter as the authorization code. Copy the code parameter, as it will be used in the next step.

The authorization code expires in 10 minutes. If it expires, repeat from step 1 to retrieve it.

1

{your_redirect_url}?code={your_code}&state=state1

4. Access token request

The access token is generated using the retrieved authorization code.

The details of the parameters needed are as follows:

Request header

For the Authorization header, set the value by connecting the following values:

  • The string "Basic "
  • A Base64 encoded Client ID and Client Secret, in the format of "ClientID:ClientSecret"

For example, if the client ID is "clientid" and the client secret is "clientsecret", specify "Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0".

Request body
Parameter Required Description
grant_type Yes Specify authorization_code.
redirect_uri Yes The redirect endpoint, which must be the same value stated in Step 1. Make sure to encode the URL.
code Yes The authorization code retrieved in the previous step.

Example

1
2
3
4

curl -X POST https://{subdomain}.kintone.com/oauth2/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -H "Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0" \
 -d "grant_type=authorization_code&redirect_uri={your_redirect_url}&code={your_code}"
Response

The details of the responses with parameters are as follows:

Parameter Description
access_token The authentication token when executing the API. The validity period is 1 hour.
refresh_token The token to obtain a new access token when an access token expires.
token_type The token type. Always specify bearer.
expires_in The access token expiration time (seconds).
scope The scope permitted by the access token.

Example

1
2
3
4
5
6
7

{
   "access_token" : "P8RSOtjFudcBkpPMjcFKjkxIy_XdctPG",
   "refresh_token" : "p51R155m0aj-XR2WV1TABR5NA9s3TAT0",
   "token_type" : "bearer",
   "expires_in" : 3600,
   "scope" : "k:app_record:read"
}
When the access token expires

If the access token expires, use refresh_token to retrieve the access token. The refresh_token do not expire.

The details of the parameters needed for using the refresh_token are as follows:

Parameter Required Description
grant_type Yes Specify refresh_token.
refresh_token Yes Refresh token obtained from the following section:
Access token request.

Example

1
2
3
4

curl -X POST https://{subdomain}.kintone.com/oauth2/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -H "Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0" \
 -d "grant_type=refresh_token&refresh_token={your_refresh_token}"

Response

1
2
3
4
5
6

{
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type" : "bearer",
   "expires_in":3600,
   "scope" : "k:app_record:read"
}

5. API execution

Run the Kintone API using the retrieved access token by setting the access token in the Authorization: Bearer header. Only the APIs defined in the scope can be used with this access token.

In the example below, the Get Record API is run.

1

curl -H "Authorization: Bearer {your_access_token}" "https://{subdomain}.kintone.com/k/v1/record.json?app={appID}&id={recordID}"

Response

1
2
3

{
  "record": [...]
}

For more information on Get Record API, refer to the following article:
Get Record

Important Notes

  • OAuth client features cannot be used from Kintone domains that use IP restrictions, unless the IP of the OAuth Client is white-listed on the IP restriction settings. For more information on IP restrictions+, refer to the following article from the Kintone help:
    IP Address Restrictions (External link)
  • Refresh tokens do not expire.

Limitations

  • Up to 20 OAuth clients can be registered
  • Up to 10 refresh tokens can be generated from 1 OAuth client for 1 user.
  • Authorization codes and access tokens have expiry times. Expired codes/tokens will return errors.
    • Authorization codes are valid for 10 minutes.
    • Access tokens are valid for 1 hour.