Description
The RenewToken API allows devices and users to renew access tokens for themselves before they expire. Owners can also renew access tokens on behalf of devices and users.
Renewing a token: Token renewal can only be made through https. To do so; a device or a user will have to call RenewToken using token authentication. 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 a user's token, and a token that is bound to a specific referrer can't be renewed by a different one (See the table below for more information about the allowed request parameters).
Specific Request Parameters
(Refer to Common Request Parameters)
Name | Description | Required | Default | Possible Values |
---|---|---|---|---|
apsws.id | Sent in case of renewing a device or user token. | No |
| |
apsdb.authToken | Sent in case of renewing a token for a device or a user. It contains the token that should be renewed. | No |
| |
apsdb.bindReferrer | Sent in case of generating a user's token. It specifies if the token belongs to the referrer that is set in the header. | No | True when generating a token for a user. | true/false |
apsdb.tokenInCookie | Sent in case of generating a user's token. It specifies if the new token should be returned in a cookie in the response header after it is renewed. | No | false | true/false |
apsdb.runAs | Allows the owner to renew a token on behalf of a user or a device. | No |
| String value representing the id of the user or device |
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 of a token renewal.
{ "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)
Error | Message | Status Code |
---|---|---|
INVALID_PARAMETER | The parameter [paramName] is not allowed in RenewToken Invalid parameter apsdb.runAs | 400 |
INVALID_REQUEST | RenewToken is not allowed over non-secure connections. RenewToken must not be called anonymously Token-based authentication is not allowed for account owners | 400 |
INVALID_PARAMETER_VALUE | Eternal tokens cannot be renewed. | 400 |
INVALID_TOKEN | Could not find the token [token]. | 400 |
INTERNAL_ERROR | 500 | |
INVALID_SIGNATURE | 400 | |
MALFORMED_REFERER | Invalid originating referrer from the Referer header [RefererHeaderString] | 400 |
PARAMETER_REQUIRED | The parameter [apsdb.authToken] is required in RenewToken. | 400 |
Examples
Sample Request to renew a token
Request URL: http://sandbox.apstrata.com/apsdb/rest/[AuthenticationKey]/RenewToken?apsws.time=[timestamp]&apsws.authSig=[signature]
Sample Response
Success XML:
<response> <metadata> <requestId>0867595f-6d8e-4754-9d7b-400b61eadf23</requestId> <status>success</status> </metadata> <result> <apsdb.authToken>1585C0147E563116EB1E74A4A060875B</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": "f67293cf-74f0-42ef-9284-64741a9e157e", "status": "success" }, "result": { "apsdb.authToken": "EA60872994E44794F6B54997FEE52C28", "apsdb.tokenExpires": "1800", "apsdb.tokenLifetime": "7200" } }}