Child pages
  • RenewToken
Skip to end of metadata
Go to start of metadata

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.

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

  1. 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) 
  2. 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) 
  3. 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)
  4.  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:

  1. Token-based authentication is enabled for user and device requests only. Owner requests must use signatures.
  2. 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.


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
The parameter [paramReferrerName] can only be [true] or [false]

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
Token-based authentication with cookies requires a referrer to be set

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"
  }
}}
  • No labels