Services Token

This module adds token based authentication for services. Access tokens expire after a given period of time and are invalidated automatically if a user changes her username or the password or if she gets blocked by an administrator. This mechanism is extendable and therefore allows for site specific policies. E.g., in some cases it is desirable to invalidate an access token whenever some permissions change.

A services action provided by this module allows clients to (re-)generate access tokens. Hence, client applications may renew their access tokens automatically.

The flexible invalidation scheme and automatic expiry makes this module an ideal candidate for distributing subscription based paid content.

Authentication protocol

In order to simplify integration with HTTP clients but also with intermediate proxies, the Authorization header is used to transmit the authentication token, i.e. the token can be used as the basic auth username and the password is left blank. This method is preferable to query parameter since proxies will automatically exclude requests if that header is present. Also query parameters are more likely to end up in server logs and the browser history, increasing the likelihood of leaking the token to third parties. Note that neither of those methods can be used safely over insecure connections, HTTPS is mandatory for both.

The token-generate action can be configured to accept username and password in addition to an existing valid token. As a result, a client application which is started for the first time may authenticate with user credentials in order to retrieve the authentication token, which is then stored client side and used for any subsequent requests.

Client examples

Generate a token

curl -XPOST http://my_username:topsecret@example.com/api/services_token/generate
{"expires":"2015-12-07T20:39:47+0100","token":"1.5665e083.RJG0CdymRKqFQJKeIV8nflwIhrr8KVrmAy6kpWft5nU"}

Use the token to retrieve data

curl -XGET http://1.5665e083.RJG0CdymRKqFQJKeIV8nflwIhrr8KVrmAy6kpWft5nU:@example.com/api/user/1
{"uid":"1","name":"my_username",...}

Regenerate a token

curl -XPOST http://1.5665e083.RJG0CdymRKqFQJKeIV8nflwIhrr8KVrmAy6kpWft5nU:@example.com/api/services_token/generate
{"expires":"2015-12-07T20:47:05+0100","token":"1.5665e239._UgtElc0RKDfj0EemIUjnM-Q90QK65MVAPhEP3m8Lq8"}