Description

1- Validating credentials: The validation can be requested for devices, users or account owners, to do so; one needs to call the VerifyCredentials API by simply signing the request. It will return a success response if the credentials are valid or an INVALID_SIGNATURE otherwise.

2- Generating a token: Account owners are not allowed to generate tokens for themselves, it has to be a device or user request sent over https. To do so; a device or a user will have to call VerifyCredentials by signing the request and passing the parameter apsdb.action=generate; the token will be returned upon success. Owners can only generate a token for a device or a user by passing their respective identifier in the parameter apsdb.runAs.

The parameters apsdb.tokenExpires and apsdb.tokenLifeTime are not mandatory when generating a token. For both devices and users, if only one of these parameters is passed, the system configuration default value will be set for the second one. If none of these parameters is passed an eternal token will be generated for the device. However, system configuration default values will be set for the user's token expiry and lifetime. (See the table below for more information about the allowed request parameters).

Note: Default and maximum expiry and life time values can always be configured and modified by the account owner.

3- Renewing a token ( this action is deprecated, henceforward you should use the RenewToken API): Token renewal can only be made through https. To do so; a device or a user will have to call VerifyCredentials using token authentication instead of signing the request, passing their identifier as a parameter (apsws.id) and passing the parameter apsdb.action=renew. The token passed to the request will be renewed and the new token will be returned upon success. Account owners are only allowed to renew tokens by passing the parameter apsdb.runAs.

A token will be renewed only if it hasn't expired and it can't be renewed past its life time, in addition whenever a token is renewed and a new token is returned, the old one would still remain valid for 5 seconds. Unlike users, the devices can have eternal tokens. Eternal tokens cannot be renewed.

The parameter apsdb.bindReferrer must be set to true to take the referrer header into account when renewing the token, and a token that is bound to a specific referrer can't be renewed by another referrer (See the table below for more information about the allowed request parameters).

Specific Request Parameters

(Refer to Common Request Parameters)

Specific Response Elements

(Refer to Common Response Elements)

The following specific "result" element is a child of the common root element "response" and a sibling of the common "metadata" element. It will be returned only in the case where a device or user has asked to generate or renew a token.

{
	"result": {
		"apsdb.authToken": "hash string representing a token",
		"apsdb.tokenExpires": "token expiry time in seconds",
		"apsdb.tokenLifetime": "token lifetime in seconds"
	}
}

Note: If the apsdb.tokenInCookie request parameter is true, then the token will be returned as cookie in the response header. This applies only for users' tokens; Devices' token cannot be bound to a referrer nor set in cookies

Specific Logical Errors

(Refer to Common Logical Error Codes)

Examples

Sample Request to generate a token

Request URL: http://sandbox.apstrata.com/apsdb/rest/[AuthenticationKey]/VerifyCredentials?apsws.time=[timestamp]&apsws.authSig=[signature]

POST parameters:

apsws.id=john
apsdb.action=generate
apsdb.bindReferrer=true
apsdb.tokenExpires=1800

Sample Response

Success XML:

<response>
	<metadata>
		<requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
		<status>success</status>
	</metadata>
	<result>
		<apsdb.authToken>1FFB2081F4E4A0680D72E469AEDB79AC</apsdb.authToken>
		<apsdb.tokenExpires>1800</apsdb.tokenExpires>
		<apsdb.tokenLifetime>7200</apsdb.tokenLifetime>
	</result>
</response>

Failure XML:

<response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd">
    <metadata>
        <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
        <status>failure</status>
        <errorCode>[errorCode]</errorCode>
        <errorDetail>[failMsg]</errorDetail>
    </metadata>
</response>

Sample JSON Response

{"response": {
  "metadata": {
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "success"
  },
  "result": {
    "apsdb.authToken": "51D589FE0FC258CE714242060C9CA04E",
    "apsdb.tokenExpires": "1800",
    "apsdb.tokenLifetime": "7200"
  }
}}