

server.php
?action=get_token_count
&email=[email address]

Return:
token_count
seconds_per_token_earned
token_cap
seconds_until_next_token
OK
-or-
DENIED


DENIED if email is unknown to server (will be know the first time a server
spends a token for this email).

Note that this call has no security token.  This simplifies the
client code which fetches this value.  I can't imagine a situation where the 
number of life tokens associated with an email address is valuable to an
attacker.

seconds_until_next_token is -1 if the player is not in the process of
earning a token (for example, if they're at or above the cap already)




server.php
?action=get_sequence_number
&email=[email address]

Return:
sequence number
OK

Gets next valid sequence number associated with email.  Note that even if
email is unknown to server, 0 will be returned so that first life can be
submitted.



server.php
?action=spend_token
&email=[email address]
&sequence_number=[int]
&hash_value=[hash value]

Return:
OK
-or-
DENIED

Used by game servers to indicate that a given email has spent a life token.

DENIED is returned if there are no life tokens left.


hash_value is computed on both ends with:

HMAC_SHA1( $shared_secret, $sequence_number )


Where $shared_secret is a secret string known to both the lifeTokenServer and
the game servers that have permission to spend tokens.

If sequence number is <= previously used sequence number for this email address,
request will be rejected.



server.php
?action=refund_token
&email=[email address]
&sequence_number=[int]
&hash_value=[hash value]

Return:
OK
-or-
DENIED

Used by game servers to indicate that a given email needs a token refunded.

DENIED is returned if the email isn't known
