Description

The GenerateToken API allows devices and users to generate access tokens for themselves. An application owner can generate a token for a user or device by using apsdb.runAs.

What is a Token?

In Apstrata, all requests must be authenticated. There are four methods for authenticating Apstrata requests:

Default Signature: This is the most secure method of authentication because it requires hashing all content of a request along with the secret of the account or the password of the user or the device and then sending the hash. (read more)
Simple Signature: This is the easiest method of authentication. It requires hashing a few select parameters along with the secret of the account or the password of the user or the device and then sending the hash. It is recommended for testing and for applications that do not have access to all parameters, e.g., files, in a request. (read more)
Token-Based Authentication: This is the recommended method of authentication for applications that make most requests with Apstrata users and devices, as opposed to owners, for use with SSL encrypted connections over HTTP POST. It provides a similar experience to sessions since a Token is generated and renewed over a period of time, without the need to generate a signature for every request. (read more)
Bearer Token Authentication: This authentication allows the users and devices to issue a request using a bearer token in the header. In order to issue a request with a token bearer header, you first need to generate a token for a user or a device. Users and devices make authenticated requests with a bearer token using the Authorization request header field. (read more)

A Token can be used to authenticate a user or a device in place of a signature. This allows the creation of applications that do not need access to the passwords of the users and devices which are required for signature generation. Tokens provide a layer of simplicity, but must obey the following restrictions:

Token-based authentication is enabled for user and device requests only. Owner requests must use signatures.
Token-based authentication is enabled under secure (https) connections only.

A Token can be created or renewed using GenerateToken, RenewToken and VerifyCredentials APIs. It can then be passed as a parameter to requests instead of the signature.

When no longer needed, Token can be deleted and cleared using DeleteToken.

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 GenerateToken by signing the request; 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.

Specific Request Parameters

(Refer to Common Request Parameters)

Name	Description	Required	Default	Possible Values
apsws.id	Sent in case of generating a device or a user token.	No		Valid device or user's identifier
apsdb.tokenExpires	It contains the relative time in seconds after which the token expires and becomes unusable.	No	1800 seconds (30 minutes)	Relative time in seconds. It should always be less or equal to 86400 seconds (24 hours).
apsdb.tokenLifetime	It contains the relative time in seconds after which the token cannot be renewed. After that amount of time, the token will be invalidated and a signature will be needed to be able to generate a new token.	No	7200 seconds (2 hours)	Relative time in seconds. It should always be less or equal to 604800 seconds (1 week).
apsdb.bindReferrer	Should be sent in case of generating a user's token . It specifies if the token should be bound to the referrer.	No	true	true false
apsdb.tokenInCookie	Should be sent in case of generating a user's token. It specifies if the token should be returned in a cookie in the response header.	No	false	true false
apsdb.runAs	Allows the owner to generate a token on behalf of a user or a device.	No		Valid device or user identifier

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 in the case where a device or user has asked to generate 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 can neither be bound to a referrer nor set in cookies.

Specific Logical Errors

(Refer to Common Logical Error Codes)

Error	Message	Status Code
INVALID_PARAMETER	The parameter [paramName] is not allowed in GenerateToken Account has enforced binding to referrer when generating tokens The parameter [paramReferrerName] can only be [true] or [false] Invalid parameter apsdb.runAs	400
INVALID_REQUEST	GenerateToken must not be called anonymously Token-based authentication is not allowed for account owners Token Generation is not allowed over non-secure connections. Token-based authentication with cookies requires a referrer to be set	400
INVALID_PARAMETER_VALUE	The parameter [apsdb.tokenExpires] is not a valid number. The parameter [apsdb.tokenLifetime] is not a valid number. The parameter [apsdb.tokenExpires] can't be a zero or a negative number. The parameter [apsdb.tokenLifetime] can't be a zero or a negative number. The parameter [apsdb.Lifetime] must be equal to or less than [xxx] The parameter [apsdb.tokenExpires] must be equal to or less than [xxx] The parameter [apsdb.tokenExpires: xxx] must be equal to or less than [apsdb.tokenLifetime: xxx]	400
INTERNAL_ERROR		500
INVALID_SIGNATURE		400
INVALID_IDENTIFIER		400
MALFORMED_REFERER	Invalid originating referrer from the Referer header [RefererHeaderString]	400
TOO_MANY_TOKENS	The total number of tokens must not exceed [tokenLimit]	400

Examples

Sample Request to generate a token

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

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"
  }
}}

Child pages

GenerateToken

Description

Specific Request Parameters

Specific Response Elements

Specific Logical Errors

Examples