Revoke Token

Overview

Token revocation is an important security feature that allows applications to invalidate access and refresh tokens when they are no longer needed. This is particularly important when a user logs out, uninstalls your application, or when you detect suspicious activity.

When to Revoke Tokens

You should revoke tokens in the following scenarios:

• User Logout: When a user explicitly logs out of your application
• Uninstallation: When a user uninstalls your application
• Password Change: When a user changes their password
• Suspicious Activity: When you detect suspicious activity or a potential security breach
• Token Compromise: When you believe a token may have been compromised
• Permission Changes: When a user's permissions or roles change significantly

Token Revocation Endpoint

To revoke a token, make a POST request to the token revocation endpoint:

POST https://api.iiniit.com/oauth2/revoke
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {base64(client_id:client_secret)}

token=TOKEN_TO_REVOKE&
token_type_hint=access_token

Request Parameters

Response

A successful revocation request will return a 200 OK response with an empty body. If the token is invalid or already revoked, the server will still return a 200 OK response to prevent information leakage.

Revoking Different Token Types

Revoking Access Tokens

When you revoke an access token, it immediately becomes invalid for API requests. However, the associated refresh token may still be valid.

POST https://api.iiniit.com/oauth2/revoke
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {base64(client_id:client_secret)}

token=ACCESS_TOKEN&
token_type_hint=access_token

Revoking Refresh Tokens

When you revoke a refresh token, it becomes invalid for obtaining new access tokens. Additionally, all access tokens that were issued using this refresh token are also revoked.

POST https://api.iiniit.com/oauth2/revoke
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {base64(client_id:client_secret)}

token=REFRESH_TOKEN&
token_type_hint=refresh_token

Code Examples

JavaScript Example

/**
 * Revoke an OAuth2 token
 * @param {string} token - The token to revoke
 * @param {string} tokenTypeHint - The type of token: 'access_token' or 'refresh_token'
 * @param {string} clientId - Your OAuth2 client ID
 * @param {string} clientSecret - Your OAuth2 client secret
 * @returns {Promise} - True if revocation was successful
 */
async function revokeToken(token, tokenTypeHint, clientId, clientSecret) {
  try {
    // Create Basic Auth header
    const authHeader = 'Basic ' + btoa(`${clientId}:${clientSecret}`);
    
    const response = await fetch('https://api.iiniit.com/oauth2/revoke', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Authorization': authHeader
      },
      body: new URLSearchParams({
        token: token,
        token_type_hint: tokenTypeHint
      })
    });
    
    // A successful revocation returns 200 OK
    return response.status === 200;
  } catch (error) {
    console.error('Error revoking token:', error);
    return false;
  }
}

// Example usage for user logout
async function logoutUser() {
  // Get tokens from storage
  const tokens = JSON.parse(localStorage.getItem('oauth_tokens'));
  
  if (tokens && tokens.refresh_token) {
    // Revoke the refresh token (this also invalidates related access tokens)
    const success = await revokeToken(
      tokens.refresh_token,
      'refresh_token',
      'YOUR_CLIENT_ID',
      'YOUR_CLIENT_SECRET'
    );
    
    if (success) {
      console.log('Successfully logged out');
      // Clear tokens from storage
      localStorage.removeItem('oauth_tokens');
      // Redirect to login page or home page
      window.location.href = '/login';
    } else {
      console.error('Failed to revoke token');
      // Handle error - may still want to clear local tokens
      localStorage.removeItem('oauth_tokens');
    }
  } else {
    console.warn('No tokens to revoke');
    // Redirect to login page
    window.location.href = '/login';
  }
}

Security Considerations

• Client Authentication: Always authenticate your client when making revocation requests to prevent unauthorized token revocation.
• HTTPS: Always use HTTPS for token revocation to prevent token interception.
• Error Handling: Handle revocation errors gracefully, but always clear local tokens even if revocation fails.
• Revocation Confirmation: Do not rely on successful revocation for security-critical operations. Always clear local tokens regardless of the revocation result.
• Rate Limiting: Be aware that token revocation endpoints may be rate-limited to prevent abuse.

Troubleshooting

Next Steps

Now that you understand how to revoke tokens, you can:

• Learn about token security best practices
• Explore advanced authentication scenarios
• Understand error handling and best practices