Daikin Airzone Quick setup guide

API Integration Manual
For
Daikin DKN Cloud Wi-Fi Adaptor
IM-DKNAPI-201908

TABLE OF CONTENTS
1Introduction.......................................................................................................................................... 2
2Authentication...................................................................................................................................... 3
2.1 Oauth2 Fundamentals....................................................................................................................................... 3
2.1.1 Oauth Roles ............................................................................................................................................... 3
2.1.2 Third Party Client Application Registration............................................................................................... 3
2.1.3 Client ID and Client Secret......................................................................................................................... 3
2.2 Oauth2 Authorization Code Grant Type............................................................................................................ 4
2.2.1 Refresh Token............................................................................................................................................ 5
2.3 Open API OAuth2 Implementation ................................................................................................................... 5
2.3.1 Web Interface............................................................................................................................................ 5
2.3.2 Programmatic Interface............................................................................................................................. 7
2.4 Oauth2 Best Practices ..................................................................................................................................... 10
3API..................................................................................................................................................... 12
3.1 Status Requests ............................................................................................................................................... 12
3.1.1 Devices..................................................................................................................................................... 12
3.1.2 Device State............................................................................................................................................. 14
3.2 Command Requests......................................................................................................................................... 14
3.2.1 Device –State.......................................................................................................................................... 15
3.2.2 Device –Setpoint..................................................................................................................................... 15
3.2.3 Device –Mode......................................................................................................................................... 15
3.2.4 Device –Speed ........................................................................................................................................ 16
4Errors................................................................................................................................................. 17

API Integration Manual for Daikin DKN Cloud Wi-Fi Adaptor
2
1 INTRODUCTION
The following document describes the use of the DKN Cloud NA third party API, further on called
Open API, including the authentication flow and all available requests/actions.

API Integration Manual for Daikin DKN Cloud Wi-Fi Adaptor
3
2 AUTHENTICATION
The authentication mechanism, which allows a third party service to connect to the DKN Cloud NA
ecosystem, is based on the OAuth2 standard implementation. OAuth2 is an authorization
framework that enables applications to obtain limited access to user accounts on an HTTP service.
It works by delegating user authentication to the service that hosts the user account, and
authorizing third-party applications to access the user account. The following sections will provide
an overview of OAuth2 roles, the Authorization Code grant type (Authorization flow used for the
Open API) and how it’s been adopted to work with the Open API. This section is guided towards
developers.
2.1 Oauth2 Fundamentals
2.1.1 Oauth Roles
Oauth defines four roles:
Resource Owner, User: The resource owner is the user who authorizes an application to access
their account. The application's access to the user's account is limited to the "scope" of the
authorization granted (e.g. read or write access). In this case, the user corresponds to a
registered user in the DKN Cloud NA App, and the allowed “scopes” by the Open API are the
user’s devices and groups information.
Resource / Authorization Server, API: The resource server hosts the protected user accounts,
and the authorization server verifies the identity of the user then issues access tokens to the
application. In the Open API implementation, the DKN Cloud NA ecosystem fulfills both the
resource and authorization server roles.
Client, Third Party Application: The client is the third party application that wants to access the
user's account. Before it may do so, it must be authorized by the user, and the authorization
must be validated by the Server.
2.1.2 Third Party Client Application Registration
Before using Oauth, the third party client application must be registered with the Open API service,
where the following details of the application must be provided:
Application Name
List of Redirect URI or Callback URL
The redirect URI is where the Open API will redirect the user after they authorize (or deny) the
application, and therefore the part of the application that will handle authorization codes or access
tokens. This must be seen as a list of valid URLs. As we will see next, on the authentication
process using a web interface based flow, the application must specify a redirect URL. This URL
must match one of the registered URLS. This is a safety measure used to ensure that the user will
only be directed to appropriate locations.
As of now, this registration is done exclusively on demand, and requires manual interaction
of the system administrator of the DKN Cloud NA ecosystem.
2.1.3 Client ID and Client Secret
Once the third party application is registered, the Open API service will issue "client credentials" in
the form of a client identifier and a client secret. The Client ID is a publicly exposed string that is

API Integration Manual for Daikin DKN Cloud Wi-Fi Adaptor
4
used by the service API to identify the application, and is also used to build authorization URLs that
are presented to users. The Client Secret is used to authenticate the identity of the application to
the service API when the application requests to access a user's account, and must be kept private
between the application and the API.
2.2 Oauth2 Authorization Code Grant Type
OAuth 2 defines four grant types, each of which is useful in different cases. The one used for the
Open API corresponds to the Authorization Code Grant Type. It’s the most commonly used
because it is optimized for server-side applications, where source code is not publicly exposed, and
Client Secret confidentiality can be maintained. This is a redirection-based flow, which means that
the application must be capable of interacting with the user-agent (i.e. the user's web browser) and
receiving API authorization codes that are routed through the user-agent. Nevertheless, it can also
be used with other server-side services which lack of web interface (programmatic interface).
Here describes the authorization code flow:
The above diagram represents a typical authorization flow.
Here is a more detailed explanation of the steps in the diagram:
1. The application requests authorization to access service resources from the user
2. The user must log in to the Open API environment and authorize the request.
3. If the user authorized the request, the application receives an authorization grant (Code)
4. The application requests an access token from the authorization server (API) by presenting
authentication of its own identity (Client Secret and Client ID), and the authorization grant (Code).
5. If the application identity is authenticated (registered in the Open API environment) and the
authorization grant is valid (Code hasn’t expired or already been used), the authorization server (API)
issues a pair of access token/refresh token to the application. Authorization is complete.

API Integration Manual for Daikin DKN Cloud Wi-Fi Adaptor
5
From now on, the application is authorized to make requests to the API in behalf of the user,
provided the request presents the access token for authentication. If the access token is valid, the
resource server (API) serves the resource to the application.
2.2.1 Refresh Token
The authorization response contains a pair of tokens: an access token and a refresh token. The
access token is the token used in every request made to the API to authenticate the request in
behalf of the user. The refresh token on the other hand is used for requesting a new access token
when this one expires.
Once the application has an access token, it may use the token to access the user's account via the
API, limited to the scope of access, until the token expires or is revoked. After an access token
expires, using it to make a request from the API will result in an "Invalid Token Error" (401 status).
At this point, the refresh token can be used to request a fresh access token from the authorization
server.
Now that the Oauth2 foundations have been explained, we will describe in detail the different
requests and responses handled by the Open API. The following must be used as an
implementation reference by the third party services for a successful integration with the DKN Cloud
NA’s Open API.
2.3 Open API OAuth2 Implementation
As prerequisites, users must have a valid account in both environments (third party application and
DKN Cloud NA), the third party application must be registered as an authorized entity by DKN
Cloud NA (meaning that the third party will have a valid client_id/client_secret token pair), and for
third party applications with web interface, a valid Redirect URI.
Since the authentication flow involves the linking of accounts between services, the user must first
log in to DKN Cloud NA and authorize the third party service to access his information. This can be
done in two ways: through the DKN Cloud NA website (for third party services with their own
websites/applications) or through the programmatic interface (recommended for integration and
automation systems).
All requests must be done using HTTPS protocol, and will throw an error if trying to use plain HTTP.
Note: the following HTTP request examples will be done using the cURL agent format.
2.3.1 Web Interface
Step 1. If the third party application wants to make the authorization through a web interface based
flow, the application must redirect the user to the following authorization URL:
https://dkncloudna.com/#/oauth?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBA
CK_URL&scope=installations+devices&state=STATE_TOKEN
Here is an explanation of the link components. The parameters are set in querystring format:
https://dkncloudna.com/#/oauth the API authorization endpoint.
client_id=CLIENT_ID: the application's client ID (how the API identifies the application).

API Integration Manual for Daikin DKN Cloud Wi-Fi Adaptor
6
redirect_uri=CALLBACK_URL: where the service redirects the user-agent after an
authorization code is granted. This value must match one of the valid redirect URLs
specified in the registration process.
response_type=code: specifies that your application is requesting an authorization code
grant.
scope=installations+devices: specifies the level of access that the application is
requesting. In the case of Open API, the scopes must be installations and devices.
state=STATE_TOKEN: this parameter preserves, as an encoded format, some state
object set by the client in the Authorization request and makes it available to the client in
the response. Used to mitigate CSRF attacks (explained later in more detail).
When the user clicks the link, they must first log in to the service, to authenticate their identity
(unless they are already logged in). In case the user isn’t logged in to DKN Cloud NA, this link will
redirect the user to the following login page:
Step 2. Once the user is logged in, an authorization site will appear which will request the user to
authorize or deny the third party service to access the user’s information regarding installations and
devices stored in DKN Cloud NA:

API Integration Manual for Daikin DKN Cloud Wi-Fi Adaptor
7
In this screenshot, the name of the third party application would be visible where the EXAMPLE text
is set. This same is the name provided on the registration process.
Step 3. Once the user authorizes the third party service, the web page will redirect the user-agent
to the application redirect URI specified in the first request, along with an authorization code. This
redirect URI must match one of the valid redirect URLs specified during the client registration. The
authorization code is a temporary code that the client will exchange for an access token. It will be
passed in querystring format. The redirect would look something like this (assuming the application
redirect URL is "example.com"):
https://example.com/?code=hLRlrpTIRUz96crm9PmH5PafXbE4JOAV
At this point, the application has a valid authorization code and can request an Access token. The
remaining requests involved will be explained after describing the programmatic interface access,
since they are the same for both flows.
2.3.2 Programmatic Interface
This interface basically performs the actions described above (Login and Authorize), but without the
need of a browser; only through HTTPS requests. This method is suited for the integration in home
automated systems/BMS. We will describe the structure and format of each of the requests.
Step 1 and 2. Login:
-REQUEST:
-POST https://www.dkncloudna.com/api/v1/auth/login/dknUsa
-HEADERS:
oAccept: application/json
oContent-Type: application/json
-BODY: JSON body parameters:
oemail: (String) user email
opassword: (String) user password
-EXAMPLE:
curl --location --request POST "https://www.dkncloudna.com/api/v1/auth/login/dknUsa" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data "{\"email\": \"[e-mail]\", \"password\": \"examplePassword\"}"
-RESPONSE: This returns a JSON object, where we only are interested in only one of its properties:
token.
Example response:
{
…
"token": "R7k6xX3HsHH1LIPYrCV5SbtYNH7rzFlb…",
…
}
The value of this field is needed for the next request. It acts as an authentication token for the DKN
Cloud NA environment, identifying the request in behalf of the user.
Step 3. Authorization of the third party service:

API Integration Manual for Daikin DKN Cloud Wi-Fi Adaptor
8
-REQUEST:
-POST https://www.dkncloudna.com/api/v1/users/oauth2/authorize
-HEADERS:
oAccept: application/json
oContent-Type: application/json
oAuthorization: Bearer TOKEN_VALUE
-The value in the Authorization header is the value of the token response property of the
Login response.
-BODY: JSON body parameters:
oentityName: (String) name of the third party entity, as registered when its credentials were
issued.
oclient_id: (String) value of the client_id token issued for the entity
oscopes: (String[]) scopes to authorize. Currently this property must equal to an array of two
String elements => devices, installations
-EXAMPLE:
curl --location –request POST "https://www.dkncloudna.com/api/v1/users/oauth2/authorize?" \
--header "Content-Type: application/json" \
--data "{\"entityName\": \"ENTITY_NAME\", \"client_id\": \"CLIENT_ID\", \"scopes\": [\"devices\",
\"installations\"]}"
-RESPONSE: This returns a JSON object, with only one property: redirectUri. The value of this
property will be one of the registered redirect URLs of the entity plus the code parameter (same
format as described in the Web interface process).
Example response:
{
" redirectUri": "https://example.com/?code=9zHBr2TwEkUanHTlLGvs5EjCPOvdBAHF "
}
The remaining requests are common for both interfaces.
Step 4: Application Requests Access Token. The value of code is used by the third party to ask
DKN Cloud NA for the first access token on behalf of the user. This is a one time use, short lived
token, so it must be used immediately after being received. This code is used in the following
request:
-REQUEST:
-POST https://www.dkncloudna.com/api/v1/open/oauth2/token
-HEADERS:
oContent-Type: application/x-ẃww-form-urlencoded
oAccept: application/json
-BODY: application/x-www-form-urlencoded type body parameters:
ogrant_type: (String) its value must be "authorization_code".
oclient_id: (String) value of the client_id token issued for the entity.
oclient_secret: (String) value of the client_secret token issued for the entity.
ocode: (String) value of the code parameter acquired in the previous request.
-EXAMPLE:

API Integration Manual for Daikin DKN Cloud Wi-Fi Adaptor
9
curl --location --request POST "https://www.dkncloudna.com/api/v1/open/oauth2/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--form "grant_type=authorization_code" \
--form "client_id=CLIENT_ID” \
--form "client_secret=CLIENT_SECRET" \
--form "code=CODE"
-RESPONSE: This returns a JSON object, with the following four properties:
oaccess_token: token used in every request made to the API to authenticate the request in
behalf of the user.
otoken_type:Doesn’t apply; its value will always be: Bearer
oexpires_in: (Number) value in seconds specifying the lifetime of the token. By default, it will
be two hours
orefresh_token: used for requesting a new access token when this one expires.
Example response:
{
"refresh_token": "R7k6xX3HsHH1LIPYrCV5SbtYNH7rzFlb",
"token_type": "bearer",
"access_token": "duUB2GpPoEg5dBRg2giWfFb0EvBFKg3Q",
"expires_in": 7200
}
Reached this point, the third party application is authorized to access the DKN Cloud NA
environment through the Open API endpoints on behalf of the user.
When the access token expires, DKN Cloud NA will respond with 401 error codes to every request,
with the following JSON body:
{
"_error_description": "The access token is invalid or has expired",
"error": "invalid_token"
}
The third party service will then need to request a new access token for the user. In order to do so,
the service must use the value of the refresh_token property obtained in the response body of the
previous request, and use it as shown in the following request:
-REQUEST:
-POST https://www.dkncloudna.com/api/v1/open/oauth2/token
-HEADERS:
oContent-Type: application/x-ẃww-form-urlencoded
oAccept: application/json
-BODY: application/x-www-form-urlencoded type body parameters:
ogrant_type: (String) its value must be "refresh_token".
oclient_id: (String) value of the client_id token issued for the entity.
oclient_secret: (String) value of the client_secret token issued for the entity.
orefresh_token: (String) value of a valid refresh token for that user.
-EXAMPLE:
curl --location --request POST "https://www.dkncloudna.com/api/v1/open/oauth2/token" \
--header "Content-Type: application/x-www-form-urlencoded" \