Client Credentials Grant

The Client Credentials Grant flow authorizes your application for a RICOH Cloud API service. You can use this authorization flow for some, but not all, services. See Authorization Type to understand the difference of supported authorization types and find the right one for the service you wish to use.


API Flow

In the Client Credentials Grant flow, your server-side application gets authorized by providing its credentials (client ID and client secret) for RICOH Cloud API’s authorization server. The server authenticates the request and authorizes your application by issuing an access token to it. After authorization completed, your application can access granted services. The next image shows an outline of the flow:

"Client Credentials Grant"

  1. An end user accesses the application.
  2. The application requests an access token from the authorization server by including a service code for the API service you wish to use and its credentials.
  3. The authorization server authenticates the request.
  4. The authorization server issues an access token for the specified service to the application.
  5. The application sends a request with the access token.

The following sections describe the details of the authorization request and how to deal with access tokens. For deep understanding of the flow, you can take a look at Samples.

Note: You must obtain your credentials and securely store them in a location that only your application can access. To create credentials at Management Console, see Get Started for detailed instructions. Examples at Samples also demonstrates how to store credentials securely.


Client Credentials Grant provides the following endpoints:

HTTP Method URI Description
POST Token endpoint which issues access tokens

Obtain an Access Token

As described in API Flow, obtain an access token by making an request to the authorization server. The server provides a token endpoint to issue access tokens to applications.

You can obtain an access token by making a POST request to the token endpoint with required parameters. Make a request with your application’s Credentials and the service code of the service you wish you use. The following example is a request to obtain an access token for Visual Recognition API. It specifies a client ID and a client secret on the Authorization header and Visual Recognition API’s service code on scope parameter.

POST /v1/token HTTP/1.1
Authorization: Basic YTk0YWIwMmQtMTZlZC00YWM4LTgxY2ItNjBmODA1YTVlZTUwOkZqVi81d2JONDlTdWVlbkhuc3BqZHBtUUtNUlpVNU9LZXoydjdrVWs=
Content-Type: application/x-www-form-urlencoded


This endpoint supports the following headers:

Header Description
Authorization Required. Encode <ClientId>:<ClientSecret> with Base64 and specify it with Basic scheme. This endpoint supports RFC7617’s Basic Authentication Scheme. This endpoint does NOT accept credentials in HTTP body.
Content-Type Required. Set to application/x-www-form-urlencoded

This endpoint supports the following parameters:

Parameter Description
grant_type Required. This parameter specifies a grant type. Set to client_credentials to use Client Credentials Grant
scope Required. This parameter specifies the services you wish to use. Set to a list of space-delimited service codes of the services. The section Service Code lists all the supported service codes. Note that an empty string is invalid for this parameter.

Note: You can NOT specify multiple service codes in the scope parameter unless they have the same domain. If you set service codes with different domains, your request would fail.

Good scopes:


Bad scopes:


    The service codes above have different domains. ( and

To use multiple services of different domains, you need to make a request for each domain.

Successful Response

The authorization server returns a JSON-formatted response when your request succeeds. If the example request above succeeds, the server returns a response like this:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Cache-Control: no-store
Pragma: no-cache

  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJpc3MiLCJhdWQiOiJhdWQiLCJpYXQiOjE0OTU3MDkyNDksImV4cCI6MTQ5NTcxMjg0OSwiY2xpZW50X2lkIjoiYTk0YWIwMmQtMTZlZC00YWM4LTgxY2ItNjBmODA1YTVlZTUwIiwic2NvcGUiOiJpcHMuYXBpLnJpY29oL3YxL2NvbXBhcmVfZmFjZXMifQVFngz5BJSzjhqjAY6kXoB8LiL3pTtu-Ch0CUCzx0qI9e8SUwx-kZNrabui4rmYBDk2o4BsFc_wqvfP4-1sNdeT3nEWABc0FLnF4bM51BqPLRgaBT-tXtKuRVF7gKUxk8HorMlA5WKKVTfXG1cJ2WjxHqf_cnN2_3Si6dB9Zr-droqeNzkgvDZruuNMDtfNfxTkQt4gMneWsElHfmJiw1dzhdxlCeGtnvf8cVj-8uyxphS27y5iTULbg6VaXLYFp6hBKd0QdXA4q-wx7Mv89DuBrPPtwMDycadqpiyHswn5pM2nmrIpg5T9HscARn50B58T89sbHSpGK5Ckfe7wKsnA.keBJq1td6FHwctZKl33vsKVSZMe_yNLggxtZA_BOaQgycjzDynF_DZ_46G09kFEURj65tXuYORetmw4Jqe20-T-_hjD6T9GgSpJ33LUgtVmuDhG35_0rv95C-aPmPQE7KjCFPyGOky5A2uCP33K5Dv-FKLb7dIXVY610vPBU9txchVButlwlbo69k6ZkvJZFLbl-AzfOheOQ3qNg9h4auX9DJ1j28zsqzS1mrTgZElJgvq0vuO5n6RvCOTY4PAlyXlOHUQYhVpLGgxKNv6-S_FsgbHmAs6jw4LQ0z-1QFu6G1AH7Nj9xuSYES1GiLhRsYiyLdzS-gI_-HQWtFbNOCw",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "",
  "api_key": "be4fc9db0dfd4e35b2faae2e8d4df52b"

This endpoint’s responses include the following fields:

Field Type Description
access_token string An access token. Set this token as a Bearer token in the Authorization header when you make requests to RICOH Cloud API services.
token_type string The type of the access token; i.e., Bearer.
expires_in number The lifetime in seconds of the access token; e.g., 3600 (seconds) for Visual Recognition API.
scope string The scope of the access token. The token is valid only for services described in this field.
api_key string An API key. Set this key in the x-api-key header when you make requests to RICOH Cloud API services. The key is used to keep track of your API usage.

Error Response

The authorization server also returns a JSON-formatted response when your request fails. Here is an example of error response:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

  "error": "invalid_request",
  "error_description": "The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed."

Error responses include the following fields:

Field Type Description
error string An error code which summarizes the error.
error_description string The description of the error. This description might help you identify the cause of the error.

You might encounter the following errors:

HTTP Status Code Error Code Description
400 invalid_request The request is invalid. For example, this error occurs when the request does not have required parameters, when it has parameter values which are not supported, when it has duplicated parameters, or when it has multiple or invalid Credentials.
401 invalid_client Client authentication failed. For example, this error occurs when the request has unknown Credentials, when it does not contain Credentials, or when it specify unsupported authentication scheme.
400 unsupported_grant_type The specified grant_type is not supported.
400 invalid_scope The specified scope is invalid or unknown.
404 resource_not_found The URI of the request does not exist.
405 method_not_allowed The HTTP method of the request is not supported.

Manage Token Expiration

Your application needs to manage access token expiration. Access tokens offered with Client Credentials Grant expire in certain time. Also, the authorization server does not support refresh requests. So your application needs to obtain a new access token before or after expiration. You can use one of the two methods below:

1. Calculate expiration time

Use the expires_in field of token response. You can calculate expiration time by using the field which represents the lifetime of the access token and the time you have received it. Let your application calculate and manage the expiration time of access token so that it can make a token request before the token expires.

2. Detect invalid_token error

Utilize invalid_token error responses. RICOH Cloud API services verify each access token in requests and return an invalid_token error response (with status code 401) when the access token has already expired. So, when your application detects the error, let it make a token request to obtain another access token.


See Also