Logout

Revoke all tokens for the authenticated client and end the session.

Endpoint

POST /auth/logout

Authentication: Bearer token required

Headers

Authorization: Bearer {access_token}

Request Body

No request body required - the endpoint uses the authenticated client context from the Bearer token.

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "message": "Successfully logged out"
  }
}

Error Responses

401 Unauthorized

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Examples

curl -X POST {{host}}/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

<?php
$ch = curl_init('{{host}}/auth/logout');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $access_token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result = json_decode($response, true);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($httpCode === 200 && $result['success']) {
    echo "Successfully logged out";
    // Clear stored tokens
    unset($_SESSION['access_token']);
    unset($_SESSION['refresh_token']);
}

curl_close($ch);
?>

Important Notes

1. All tokens revoked: Logout revokes all access and refresh tokens for the client, not just the one used in the request
2. Immediate effect: Revoked tokens are rejected immediately on subsequent API calls
3. Clear client-side: Always remove stored tokens from your application even if the API call fails
4. New login required: After logout, you must call /auth/login again to obtain new tokens

Best Practices

1. Immediate Token Removal: Clear tokens immediately when logout is initiated
2. Error Handling: Don't prevent logout from completing if the API call fails — clear local tokens regardless
3. Credential Rotation: Use logout before rotating API credentials to ensure old tokens are invalidated