Token

Location /api/oauth2/token
This resource provides OAuth2 token management

POST

/api/oauth2/token

Description

Request a new token.

To get a token with administrator credentials you provide the "client_id" and "client_secret".

To get a token with user or thing credentials you must provide the "username" and "password".

To get a token with a refresh token you must provide the "refresh_token" and the "grant_type".

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
username 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 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.
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
refresh_token string The current refresh token for getting a new access token
grant_type string Only applies the value "refresh_token"
Sample Request 
{
  "username": "[string]",
  "password": "[string]",
  "expiresAt": "[long]",
  "client_id": "[string]",
  "client_secret": "[string]",
  "refresh_token": "[string]",
  "grant_type": "[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