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.
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 Invalid parameter apsdb.runAs | 400 |
INVALID_REQUEST | GenerateToken must not be called anonymously | 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" } }}