This documentation is for WSO2 API Manager 2.0.0. View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

Users need access tokens to invoke APIs subscribed under an application. Access tokens are passed in the HTTP header when invoking APIs. The API Manager provides a Token API that you can use to generate and renew user and application access tokens. The response of the Token API is a JSON message. You extract the token from the JSON and pass it with an HTTP Authorization header to access the API.

The topics below explain how to generate access tokens and authorize them. WSO2 API Manager supports the following common authorization grant types and you can also define additional types.

Revoking access tokens

After issuing an access token, a user or an admin can revoke it in case of theft or a security violation. You can do this by calling the Revoke API using a utility like cURL. The Revoke API's endpoint URL is http://localhost:8280/revoke.

Parameters required to invoke this API are as follows:

  • The token to be revoked
  • Consumer key and consumer secret key. Must be encoded using Base64 algorithm

For example,

curl -k -v -d "token=<ACCESS_TOKEN_TO_BE_REVOKED>" -H "Authorization: Basic aFNOM3k0aVFHVUNVZnZvdmFrVXE1U3ExQ1RRYTpYMmRvVFZSeFhEN1FfT2xLOWtzQlB2UkJCbFVh" -H "Content-Type: application/x-www-form-urlencoded" http://localhost:8280/revoke

Revoking access tokens obtained with an Implicit grant

If you obtained an access token with the Implicit grant type, you do not have to provide the client secret to revoke it. The sample cURL command to revoke an access token with Implicit grant is given below.

curl -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "token=<REFRESH_TOKEN_TO_BE_REVOKED>&token_type_hint=access_token&client_id=<CLIENT_ID>" http://localhost:8243/revoke

You receive an empty response with the HTTP status as 200. The following HTTP headers are returned:

Revokedaccesstoken: a0d210c7a3de7d548e03f1986e9a5c39
Authorizeduser: [email protected]
Revokedrefreshtoken: 5e87a8235cd4d066e15c4c989f5ecf94
Content-Type: text/html
Pragma: no-cache
Cache-Control: no-store
Date: Tue, 23 Aug 2016 19:28:52 GMT
Transfer-Encoding: chunked

Note that if you use an invalid access token, you still receive an empty response with the HTTP status as 200 but only the following HTTP headers are returned:

Content-Type: text/html
Pragma: no-cache
Cache-Control: no-store
Date: Tue, 23 Aug 2016 19:31:45 GMT
Transfer-Encoding: chunked

Configuring the token expiration time

User access tokens have a fixed expiration time, which is set to 60 minutes by default. Before deploying the API Manager to users, extend the default expiration time by editing the <AccessTokenDefaultValidityPeriod> element in the <APIM_HOME>/repository/conf/identity/identity.xml file.

Also take the time stamp skew into account when configuring the expiration time. The time stamp skew is used to manage small time gaps in the system clocks of different servers. For example, let's say you have two Key Managers and you generate a token from the first one and authenticate with the other. If the second server's clock runs 300 seconds ahead, you can configure a 300s time stamp skew in the first server. When the first Key Manager generates a token (e.g., with the default life span, which is 3600 seconds), the time stamp skew is deducted from the token's life span. The new life span is 3300 seconds and the first server calls the second server after 3200 seconds.

You configure the time stamp skew using the <TimestampSkew> element in the <APIM_HOME>/repository/conf/identity/identity.xml file.

Tip: Ideally, the time stamp skew should not be larger than the token's life span. We recommend you to set it to zero if the nodes in your cluster are synchronized.

When a user access token expires, the user can try regenerating the token.

  • No labels