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.

Contents

• API Flow
• Endpoints
• How to Obtain an Access Token
• How to Manage Token Expiration
• Samples
• See Also

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:

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.

Endpoints

Client Credentials Grant provides the following endpoints:

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
Host: auth.api.ricoh
Authorization: Basic YTk0YWIwMmQtMTZlZC00YWM4LTgxY2ItNjBmODA1YTVlZTUwOkZqVi81d2JONDlTdWVlbkhuc3BqZHBtUUtNUlpVNU9LZXoydjdrVWs=
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope=ips.api.ricoh/v1/detect_humans ips.api.ricoh/v1/detect_faces ips.api.ricoh/v1/compare_faces

This endpoint supports the following headers:

This endpoint supports the following parameters:

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:

• ips.api.ricoh/v1/detect_humans ips.api.ricoh/v1/detect_faces ips.api.ricoh/v1/compare_faces
• ips.api.ricoh/v1/detect_faces ips.api.ricoh/v1/compare_faces
• sfu.api.ricoh/v1/

Bad scopes:

• sfu.api.ricoh/v1/ ips.api.ricoh/v1/compare_faces

  The service codes above have different domains. (sfu.api.ricoh and ips.api.ricoh)

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": "ips.api.ricoh/v1/detect_humans ips.api.ricoh/v1/detect_faces ips.api.ricoh/v1/compare_faces",
  "api_key": "be4fc9db0dfd4e35b2faae2e8d4df52b"
}

This endpoint’s responses include the following fields:

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:

You might encounter the following errors:

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.

Samples

• Live Streaming Sample

See Also

• Client Credentials Grant API Reference
• The OAuth 2.0 Authorization Framework (RFC6749)