OAuth2

Location /api/apps/{appID}/oauth2/token
This resource provides OAuth2 token management for the accessed application.

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

POST

/api/apps/{appID}/oauth2/token

Description

Request a new token.

The following four types of requests are available. The request type is to be set as the "grant_type" parameter:

  • authorization_code: Request a new token with an OAuth2 authorization code. You need to fill in the parameters "client_id, "client_secret", "code", and "redirect_uri".
  • client_credentials: Request a new app admin or anonymous token. You need to fill in the parameters "client_id" and "client_secret". Note that the values you need to put in these parameters depend on the type of the token you want to get.
  • password: Request a new user/thing token with the user/thing credentials. You need to fill in the parameters "username" and "password".
  • refresh_token: Request a new access token by providing the current refresh token. You need to fill in the the parameter "refresh_token".

As users and things are entities that can be authenticated by Kii Cloud, they are considered also as the principals when referring the authentication contexts. The principalID in these cases will be the userID and thingID.

Content-Type application/x-www-form-urlencoded

All the required information to request a token. We advise to use prefixed addresses.

Params
Name Required? Type Description
grant_type Yes string

The type of the request.

  • authorization_code
  • client_credentials
  • password
  • refresh_token
client_id No string

The client_id for the OAuth2 authorization flow

  • The Kii application's clientID for getting an app admin token.
  • The Kii application's appID for getting an anonymous token.
client_secret No string

The client_secret for the OAuth2 authorization flow

  • The Kii application's clientSecret for getting an app admin token.
  • The Kii application's appKey for getting an anonymous token.
code No string The OAuth2 authorization code
redirect_uri No string The redirection URI for the authorization request
username No string

Provide one of the following for getting a user token:

  • The login name of the user
  • The email address of the user
  • The email address of the user with prefix: EMAIL:{emailAddress}
  • The phone number of the user in international format: +XXX...
  • The phone number of the user in local format: PHONE:{countryCode}-{localPhone}

The country code is in ISO-3166 format. The phone number and email address must be verified.

For getting a thing token, the vendorThingID with the prefix: VENDOR_THING_ID:{vendorThingID} must be provided
password No string The password of the user or thing
refresh_token No string The current refresh token.
Sample Request 
{
  "grant_type": "[string]",
  "client_id": "[string]",
  "client_secret": "[string]",
  "code": "[string]",
  "redirect_uri": "[string]",
  "username": "[string]",
  "password": "[string]",
  "refresh_token": "[string]"
}
Responses
200

Content-Type application/json

Successfully got a token.
Contents
Name Type Description
id string The ID of the principal (user or thing).
access_token string The access token issued by the authorization server.
expires_in long The lifetime of the access token (in seconds).
token_type string The token type. Only "Bearer" is supported.
refresh_token string The new refresh token.
400

Content-Type application/json

Could not get a token.
Contents
Name Type Description
errorCode string Oauth2 error code: "invalid_grant" or "unsupported_grant_type".
error_description string The error description.
error string Oauth2 error code

POST

/api/apps/{appID}/oauth2/token

Description

Request a new token.

The following four types of requests are available. The request type is to be set as the "grant_type" parameter:

  • authorization_code: Request a new token with an OAuth2 authorization code. You need to fill in the parameters "client_id, "client_secret", "code", and "redirect_uri".
  • client_credentials: Request a new app admin or anonymous token. You need to fill in the parameters "client_id" and "client_secret". Note that the values you need to put in these parameters depend on the type of the token you want to get.
  • password: Request a new user/thing token with the user/thing credentials. You need to fill in the parameters "username" and "password".
  • refresh_token: Request a new access token by providing the current refresh token. You need to fill in the the parameter "refresh_token".

The parameter "expiresAt" is optional for all the cases.

As user and things are entities that can be authenticated by Kii Cloud they are considered also as principals when referring authentication contexts, the principalID would be in those cases the userID or thingID.

Content-Type application/vnd.kii.OauthTokenRequest+json

All the required information to request a token. We advise to use prefixed addresses. application/json can be used as content-type for the compatibility.

Params
Name Required? Type Description
grant_type Yes string

The type of the request

  • authorization_code
  • client_credentials
  • password
  • refresh_token
code string The oauth2 authorization code
redirect_uri string The redirection URI for the authorization request
client_id string

The client_id for the OAuth2 authorization flow

  • The Kii application's clientID for getting an app admin token
  • The Kii application's appID for getting an anonymous token
client_secret string

The client_secret for the OAuth2 authorization flow

  • The Kii application's clientSecret for getting an app admin token
  • The Kii application's appKey for getting an anonymous token
username string

For getting a user token can be one of the following:

  • The login name of the user
  • The email address of the user
  • The email address of the user with prefix: EMAIL:{emailAddress}
  • The phone number of the user in international format: +XXX...
  • The phone number of the user in local format: PHONE:{countryCode}-{localPhone}

The country code is in ISO-3166 format. The phone number and email address must be verified.

For getting a thing token, the vendorThingID with the prefix: VENDOR_THING_ID:{vendorThingID} must be provided
password string The password of the user or the thing
expiresAt long The expiration date of the token. The date should be in UNIX epoch time in milliseconds.
refresh_token string The current refresh token
Sample Request 
{
  "grant_type": "[string]",
  "code": "[string]",
  "redirect_uri": "[string]",
  "client_id": "[string]",
  "client_secret": "[string]",
  "username": "[string]",
  "password": "[string]",
  "expiresAt": "[long]",
  "refresh_token": "[string]"
}
Responses
200

Content-Type application/json

Successfully got a token
Contents
Name Type Description
id string The ID of the principal (user or thing).
access_token string The access token issued by the authorization server.
expires_in long The lifetime of the access token (in seconds).
token_type string The token type. Only "Bearer" is supported.
refresh_token string The new refresh token.
400

Content-Type application/json

Could not get a token
Contents
Name Type Description
errorCode string Oauth2 error code: "invalid_grant" or "unsupported_grant_type".
error_description string The error description.
error string Oauth2 error code