How to add OAuth clients

OAuth 2.0 (External link) 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.

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 and navigate to the User & System Administration (External link) 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
response_type Yes Specify code.
scope Yes The scope. Refer to the OAuth Permission Scope article for more details on the scope. 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 Register your application to Kintone section.

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.

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
 5
 6
 7
 8
 9
10
11
12
13
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
{
   "access_token" : "P8RSOtjFudcBkpPMjcFKjkxIy_XdctPG",
   "refresh_token" : "p51R155m0aj-XR2WV1TABR5NA9s3TAT0",
   "token_type" : "bearer",
   "expires_in" : 3600,
   "scope" : "k:app_record:read"
}

The access token is included in the response which can be used to call the API. Access tokens are valid for 1 hour. If the access token expires, use the refresh token to generate a new access token. The refresh token has no expiration date.

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

Parameter Required Description
grant_type Yes refresh_token
refresh_token Yes Refresh token obtained from Access token request.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
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
{
   "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
2
3
4
5
6
curl -H "Authorization: Bearer {your_access_token}" "https://{subdomain}.kintone.com/k/v1/record.json?app={appID}&id={recordID}"

# response
{
  "record": [...]
}

Important Notes

  • OAuth client features cannot be used from Kintone domains that use IP restrictions (External link) , unless the IP of the OAuth Client is white-listed on the IP restriction settings.
  • 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.