Authorization and Discovery Service

Authorization Service and Discovery Service are working cooperatively to issue authorization tickets for client programs to use various APIs.

Authorization Service (Auth for short) is responsible for authenticating devices/users/clients, and issuing and managing tickets.

Discovery Service (Discovery for short) is responsible for authorizing whether the account/user with the client is allowed to use a specific API. The result is returned to the client as a set of tickets that are issued from Auth according to requests from Discovery.

Workflow of Authentication and Discovery

APIs

All API endpoints are listed below.

Method Description
POST /auth/token Password Authentication
POST /auth/discovery Discovery Service
POST /auth/token Token Refresh

POST /auth/token (Password Authentication)

Password Authentication API checks the given credential (username/password pair) against two sets of principals: accounts and users.

URL Structure

https://auth.beta2.ucs.ricoh.com/auth/token

Example request:

curl --request POST 'https://auth.beta2.ucs.ricoh.com/auth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=<your client id>' \
    --data-urlencode 'client_secret=<your client secret>' \
    --data-urlencode 'username=<your user_id>' \
    --data-urlencode 'password=<your password>' \
    --data-urlencode 'scope=https://ucs.ricoh.com/scope/api/auth https://ucs.ricoh.com/scope/api/discovery https://ucs.ricoh.com/scope/api/udc2' \
    --data-urlencode 'grant_type=password'
Parameter Description
content_type application/x-www-form-urlencoded
grant_type Fixed string password. Represents password authentication.
client_id Client identifier URI.
client_secret Client secret. This secret is given from client registration.
username user_id of the account or email address of the user.
password Web password associated with the user_id.
scope Scope identifiers that the client wants to use.
Service name Service scope identifier media storage service streaming service remote control service
Auth API https://ucs.ricoh.com/scope/api/auth required required required
Discovery API https://ucs.ricoh.com/scope/api/discovery required required required
UDC2 Service API https://ucs.ricoh.com/scope/api/udc2 required required required

Example response:

{
  "access_token": "<access token>",
  "refresh_token": "<refresh_token>",
  "token_type": "bearer",
  "expires_in": 182,
  "scope": "https://ucs.ricoh.com/scope/api/auth https://ucs.ricoh.com/scope/api/discovery https://ucs.ricoh.com/scope/api/udc2"
}
Key Value
access_token Access token that represents the result of the authentication. It is a non-predictable ascii string of the length less than 4096.
refresh_token Refresh token. See Token Refresh API
token_type Fixed string bearer. Represents that the access_token should be used as a Bearer Token for API requests.
expires_in Integer representing expiration time in seconds.
scope Scope identifiers that the authentication is granted for. Separated by spaces when multiple scopes are specified.

POST /auth/discovery (Discovery Service)

When a client wants to use any of the service APIs, it must know the endpoint URI and get an access authorization. Discovery provides this information as requested from the client.

Example request:

curl --request POST 'https://auth.beta2.ucs.ricoh.com/auth/discovery' \
    --header 'Authorization: Bearer <Access token obtained from Password Authentication API>' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data-urlencode 'scope=https://ucs.ricoh.com/scope/api/udc2'
Parameter Description
Authorization Present access token in Authorization request header.
content_type application/x-www-form-urlencoded
scope Service identifiers corresponding to the services requested.
Multiple identifiers should be separated by a space (%20 when encoded).
Service name Service scope identifier media storage service streaming service remote control service
Discovery API https://ucs.ricoh.com/scope/api/discovery required required required

Example response:

{
  "https://ucs.ricoh.com/scope/api/udc2": {
    "access_token": "<access token>",
    "expires_in": 182,
    "scope": "https://ucs.ricoh.com/scope/api/udc2",
    "refresh_token": "<refresh_token>",
    "id": "<your user_id>",
    "endpoints": {
      "mqtts": "mqtts://m2m.ricohapi.com/",
      "wss": "wss://sig.ricohapi.com/"
    }
  }
}
Key Value
access_token Access token that represents the authorization. It is a non-predictable ascii string of the length less than 512.
expires_in Integer representing expiration time in seconds.
refresh_token refresh token. See Token Refresh API
scope Scope identifiers that the authentication is granted for.
Separated by spaces when multiple scopes are specified.
id user_id of the account or email address of the user.
endpoint URI representing the endpoint of the service. Access method is resolved from the URI scheme, e.g. HTTPS or XMPP.
endpoints An array of endpoint URIs. This parameter is used if the service has multiple endpoints. For example, M2M service can be accessed either by MQTTS or WSS.

POST /auth/token (Token Refresh)

An Access token has a limited life time. When the access token expires, the client can request another access token with the same grant if a refresh token is included in the authorization result.

Example request:

curl --request POST 'https://auth.beta2.ucs.ricoh.com/auth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data-urlencode 'refresh_token=<refresh_token>' \
    --data-urlencode 'client_id=<your CID>' \
    --data-urlencode 'client_secret=<your client secret>' \
    --data-urlencode 'grant_type=refresh_token' \
    -D-
Parameter Description
content_type application/x-www-form-urlencoded
refresh_token Required. The refresh token issued to the client.
client_id Required. Client identifier URI
client_secret client secret. This secret is given from client registration.
grant_type Required. Fixed string refresh_token.

Example response:

Same as Password Authentication API.