diff --git a/main/docs.json b/main/docs.json index f3bb283e0a..1642f3c3c6 100644 --- a/main/docs.json +++ b/main/docs.json @@ -2075,21 +2075,25 @@ "docs/secure/tokens/delegation-tokens", { "group": "Refresh Tokens", + "root": "docs/secure/tokens/refresh-tokens", "pages": [ - "docs/secure/tokens/refresh-tokens", "docs/secure/tokens/refresh-tokens/get-refresh-tokens", "docs/secure/tokens/refresh-tokens/use-refresh-tokens", "docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration", - "docs/secure/tokens/refresh-tokens/refresh-token-rotation", - "docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation", - "docs/secure/tokens/refresh-tokens/use-refresh-token-rotation", - "docs/secure/tokens/refresh-tokens/disable-refresh-token-rotation", "docs/secure/tokens/refresh-tokens/revoke-refresh-tokens", - "docs/secure/tokens/refresh-tokens/manage-refresh-tokens-actions", + { + "group": "Refresh Token Rotation", + "root": "docs/secure/tokens/refresh-tokens/refresh-token-rotation", + "pages": [ + "docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation", + "docs/secure/tokens/refresh-tokens/use-refresh-token-rotation", + "docs/secure/tokens/refresh-tokens/disable-refresh-token-rotation" + ] + }, { "group": "Refresh Token Metadata", + "root": "docs/secure/tokens/refresh-tokens/refresh-token-metadata", "pages": [ - "docs/secure/tokens/refresh-tokens/refresh-token-metadata", "docs/secure/tokens/refresh-tokens/refresh-token-metadata/configure-refresh-token-metadata", "docs/secure/tokens/refresh-tokens/refresh-token-metadata/use-cases" ] @@ -2100,11 +2104,10 @@ "docs/secure/tokens/refresh-tokens/multi-resource-refresh-token", "docs/secure/tokens/refresh-tokens/multi-resource-refresh-token/configure-and-implement-multi-resource-refresh-token" ] - } + }, + "docs/secure/tokens/refresh-tokens/manage-refresh-tokens-actions" ] }, - "docs/secure/tokens/revoke-tokens", - "docs/secure/tokens/manage-refresh-tokens-with-auth0-management-api", "docs/secure/tokens/token-best-practices" ] } @@ -10488,6 +10491,10 @@ ] }, "redirects": [ + { + "source": "docs/secure/tokens/manage-refresh-tokens-with-auth0-management-api", + "destination": "docs/secure/tokens/refresh-tokens/revoke-refresh-tokens" + }, { "source": "docs/customize/phone-messages/customize-phone-templates", "destination": "docs/customize/phone-messages/phone-templates" @@ -14300,17 +14307,21 @@ "source": "/docs/api-auth/tutorials/adoption/delegation", "destination": "/docs/secure/tokens/delegation-tokens" }, + { + "source": "/docs/secure/tokens/revoke-tokens", + "destination": "/docs/secure/tokens" + }, { "source": "/docs/security/tokens/revoke-tokens", - "destination": "/docs/secure/tokens/revoke-tokens" + "destination": "/docs/secure/tokens" }, { "source": "/docs/tokens/guides/revoke-tokens", - "destination": "/docs/secure/tokens/revoke-tokens" + "destination": "/docs/secure/tokens" }, { "source": "/docs/tokens/revoke-tokens", - "destination": "/docs/secure/tokens/revoke-tokens" + "destination": "/docs/secure/tokens" }, { "source": "/docs/security/tokens/refresh-tokens/revoke-refresh-tokens", diff --git a/main/docs/secure/tokens/manage-refresh-tokens-with-auth0-management-api.mdx b/main/docs/secure/tokens/manage-refresh-tokens-with-auth0-management-api.mdx index 2b7f6f1de0..76985e8f20 100644 --- a/main/docs/secure/tokens/manage-refresh-tokens-with-auth0-management-api.mdx +++ b/main/docs/secure/tokens/manage-refresh-tokens-with-auth0-management-api.mdx @@ -1,13 +1,10 @@ --- +title: Manage Refresh Tokens with the Management API description: Learn how to manage refresh tokens with the Auth0 Management API. -title: Manage Refresh Tokens with Auth0 Management API --- -Auth0 issues a refresh token as a credential artifact that your application can use to get a new access token without user interaction. This allows Auth0 to shorten the access token lifetime for security purposes without involving the user when the access token expires. - The Auth0 Management API refresh token endpoints are currently are available to customers on Enterprise plans. To learn more, read [Pricing](https://auth0.com/pricing). - ## Management API endpoints @@ -50,8 +47,6 @@ The refresh Refresh tokens with [Actions](/docs/customize/actions) allows you to configure post-authentication risk detection and response capabilities to protect your applications and users against compromised refresh tokens. You can also dynamically customize the [refresh token expirations](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration). To facilitate this, post-login Actions feature two key objects: @@ -52,13 +53,11 @@ You can use these methods to dynamically customize the refresh token lifetime an * Any other dynamic criteria available during execution of the Action - The `api.refreshToken.setExpiresAt(absolute)` and `api.refreshToken.setIdleExpiresAt(idle)` methods allow to define the expiration of a refresh token, before its issuance, or modify an existing refresh token expiration during a [refresh token exchange](/docs/secure/tokens/refresh-tokens/use-refresh-tokens) flow. The `api.refreshToken.setExpiresAt(absolute)` and the `api.refreshToken.setIdleExpiresAt(idle)` methods will convert non-expiring refresh tokens to expiring refresh tokens using the defaults [Refresh Token expirations](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration) settings as maximum values. The `api.refreshToken.setIdleExpiresAt(idle)` method sets the inactivity timeout for refresh tokens. If the method is not called in every successful exchange, the inactivity timeout will be overwritten using the refresh token lifetime application settings. - ## Limitations @@ -73,8 +72,6 @@ The `api.refreshToken.setIdleExpiresAt(idle)` method sets the inactivity timeout - Both `api.refreshToken.setExpiresAt()` and `api.refreshToken.setIdleExpiresAt()` can only shorten their respective lifetimes from the current values. They cannot extend or increase the lifetime. -To learn more about refresh tokens limitations, read [Refresh Tokens limitations](/docs/secure/tokens/refresh-tokens). - ## Use cases: Revoke a refresh token You can use [Actions](/docs/customize/actions) to configure risk detections and revoke refresh tokens with the `api.refreshToken.revoke(reason)` method and the event objects. @@ -97,11 +94,6 @@ exports.onExecutePostLogin = async (event, api) => { }; ``` - - - - - In this example, a check occurs at the start of the Action to verify that the `event.authentication.ImpossibleTravel.code` is equal to the `impossible_travel_from_last_login property`. If `true`, the Action calls the `api.refreshToken.revoke()` to: * Deny the transaction @@ -129,11 +121,6 @@ exports.onExecutePostLogin = async (event, api) => { }; ``` - - - - - In this example, a check occurs at the start of the Action to keep track of the IP addresses with the `event.refresh_token.device.initial_ip` and the `event.request.ip` properties. The Action determines if the transaction IP address has changed. If `true`, the Action calls the `api.refreshToken.revoke()` to: * Deny the transaction @@ -177,11 +164,6 @@ exports.onExecutePostLogin = async (event, api) => { }; ``` - - - - - In this example, If there is a specific absolute timeout defined for an Organization, the Action sets the refresh token absolute timeout to be equal to: * Newly issued tokens: `current_time` plus `organization_refresh_token_lifetime` @@ -211,9 +193,4 @@ exports.onExecutePostLogin = async (event, api) => { }; ``` - - - - - In this example, if there is a specific idle timeout defined for the Application and the user is an Admin, the Action sets the refresh token inactivity timeout to be equal to the `current_time` plus the `refresh_token_idle_timeout`. Note that we are changing the timeout for both newly issued tokens and existing ones during refresh token exchange. diff --git a/main/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens.mdx b/main/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens.mdx index 402f001690..0401260495 100644 --- a/main/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens.mdx +++ b/main/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens.mdx @@ -1,328 +1,98 @@ --- -description: Learn how to revoke a refresh token if it gets compromised using the Authentication API, the Management API, or the Auth0 Dashboard. title: Revoke Refresh Tokens +description: Learn how to revoke a refresh token if it gets compromised using the Auth0 Dashboard, Authentication API, or Management API. --- -import {AuthCodeBlock} from "/snippets/AuthCodeBlock.jsx"; +import {AuthCodeBlock} from "/snippets/AuthCodeBlock.jsx"; import {AuthCodeGroup} from "/snippets/AuthCodeGroup.jsx"; -You can revoke refresh tokens in case they become compromised. Auth0 handles token revocation as though the token has been potentially exposed to malicious adversaries. +You can revoke refresh tokens if they become compromised. Auth0 handles token revocation as though the token has been potentially exposed to malicious adversaries. -You can also use [refresh token rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation) so that every time a client exchanges a refresh token to get a new access token, a new refresh token is also returned. Therefore, you no longer have a long-lived refresh token that, if compromised, could provide illegitimate access to resources. As refresh tokens are continually exchanged and invalidated, the threat is reduced. +Additionally, you may consider enabling [refresh token rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation) so that every time a client exchanges a refresh token to get a new access token, a new refresh token is also returned. -You can revoke a refresh token in the following ways: +## Choose whether token revocation deletes grants -* In the Dashboard -* Post a request to the Authentication API `/oauth/revoke` endpoint -* Post a request to the Management API `/api/v2/device-credentials` endpoint +A grant provides an application with access to a resource on another entity without exposing user credentials. Tokens are issued in the context of a grant. -## Refresh tokens and grants +When a grant is revoked, so are all tokens issued in the context of that grant. However, when a token is revoked, the grant does not necessarily need to be revoked. -A grant provides an application with access to a resource on another entity without exposing user credentials. Tokens are issued in the context of a grant, and when a grant is revoked, so are all tokens issued in the context of that grant. When, on the other hand, a token is revoked, this does not necessarily mean that the grant is revoked. +You can choose whether token revocation deletes the associated grant in your tenant settings: -You can choose the revocation behavior in the Dashboard tenant settings when a device is unlinked from a user in Auth0, using either the Dashboard or the Management API. +1. Go to [Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/#/tenant/advanced). - +2. In the **Settings** section. enable or disable the **Refresh Token Revocation Deletes Grant** toggle. -For existing tenants, this feature is enabled by default to preserve the existing behavior. For new tenants (as of 13 January 2021), this feature is disabled by default to ensure that the revocation of a refresh token will not revoke the grant. If a grant revocation is needed, a separate request must be sent using a grant revocation endpoint. + * Enable the toggle to delete the underlying grant when you revoke the refresh token. - + Each revocation request invalidates all other tokens based on the same authorization grant, which revokes all refresh tokens that have been issued for the same user, application, and audience. -1. Go to [Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/#/tenant/advanced) and scroll to the **Settings** section. -2. Enable or disable the **Refresh Token Revocation Deletes Grant** toggle depending on how you want the revocation to work. + * Disable the toggle to retain the underlying grant when you revoke the refresh token. - 1. Enable the toggle to delete the underlying grant when you revoke the refresh token. Each revocation request invalidates not only the specific token but all other tokens based on the same authorization grant. This means that all refresh tokens that have been issued for the same user, application, and audience will be revoked. - 2. Disable the toggle to retain the underlying grant when you revoke the refresh token. When a device is unlinked, only the associated refresh token is revoked, leaving the grant intact. + When a device is unlinked, only the associated refresh token is revoked, leaving the grant intact. -## Use the Dashboard +This feature is disabled by default for all tenants created after 13 January 2021. -You can use the Dashboard to revoke a user's authorized access to the application that issued the token. This renders the refresh token invalid, which is functionally identical to revoking the token itself. +## Revoke a refresh token -1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users), and click the name of the user to view. -2. Select the **Authorized Applications** tab. This page lists all the applications to which the user has authorized access. -3. To revoke the user's access to an authorized application, and hence invalidate the refresh token, click **Revoke**. +You can revoke a refresh token in the following ways: + +* [Using the Auth0 Dashboard](#using-the-auth0-dashboard) +* [Using the Authentication API](#using-the-authenticaton-api) +* [Using the Management API](#using-the-management-api) -## Use the Authentication API - -To revoke a refresh token, send a `POST` request to `https://{yourDomain}/oauth/revoke`. - -The `/oauth/revoke` endpoint revokes the entire grant, not just a specific token. Use the `/api/v2/device-credentials` endpoint to revoke refresh tokens. The API first validates the application credentials and then verifies whether the token was issued to the application making the revocation request. If this validation fails, the request is refused, and the application is informed of the error. Next, the API invalidates the token. The invalidation takes place immediately, and the token cannot be used again after the revocation. Each revocation request invalidates all the tokens that have been issued for the same authorization grant. - - -```bash cURL -curl --request POST \ - --url 'https://{yourDomain}/oauth/revoke' \ - --header 'content-type: application/json' \ - --data '{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }' -``` -```csharp C# -var client = new RestClient("https://{yourDomain}/oauth/revoke"); -var request = new RestRequest(Method.POST); -request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }", ParameterType.RequestBody); -IRestResponse response = client.Execute(request); -``` -```go Go -package main - -import ( - "fmt" - "strings" - "net/http" - "io/ioutil" -) - -func main() { - - url := "https://{yourDomain}/oauth/revoke" - - payload := strings.NewReader("{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }") - - req, _ := http.NewRequest("POST", url, payload) - - req.Header.Add("content-type", "application/json") - - res, _ := http.DefaultClient.Do(req) - - defer res.Body.Close() - body, _ := ioutil.ReadAll(res.Body) - - fmt.Println(res) - fmt.Println(string(body)) - -} -``` -```java Java -HttpResponse response = Unirest.post("https://{yourDomain}/oauth/revoke") - .header("content-type", "application/json") - .body("{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }") - .asString(); -``` -```javascript Node.JS -var axios = require("axios").default; - -var options = { - method: 'POST', - url: 'https://{yourDomain}/oauth/revoke', - headers: {'content-type': 'application/json'}, - data: { - client_id: '{yourClientId}', - client_secret: '{yourClientSecret}', - token: '{yourRefreshToken}' - } -}; - -axios.request(options).then(function (response) { - console.log(response.data); -}).catch(function (error) { - console.error(error); -}); -``` -```objc Obj-C -#import - -NSDictionary *headers = @{ @"content-type": @"application/json" }; -NSDictionary *parameters = @{ @"client_id": @"{yourClientId}", - @"client_secret": @"{yourClientSecret}", - @"token": @"{yourRefreshToken}" }; - -NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil]; - -NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/revoke"] - cachePolicy:NSURLRequestUseProtocolCachePolicy - timeoutInterval:10.0]; -[request setHTTPMethod:@"POST"]; -[request setAllHTTPHeaderFields:headers]; -[request setHTTPBody:postData]; - -NSURLSession *session = [NSURLSession sharedSession]; -NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request - completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) { - if (error) { - NSLog(@"%@", error); - } else { - NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response; - NSLog(@"%@", httpResponse); - } - }]; -[dataTask resume]; -``` -```php PHP -$curl = curl_init(); - -curl_setopt_array($curl, [ - CURLOPT_URL => "https://{yourDomain}/oauth/revoke", - CURLOPT_RETURNTRANSFER => true, - CURLOPT_ENCODING => "", - CURLOPT_MAXREDIRS => 10, - CURLOPT_TIMEOUT => 30, - CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, - CURLOPT_CUSTOMREQUEST => "POST", - CURLOPT_POSTFIELDS => "{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }", - CURLOPT_HTTPHEADER => [ - "content-type: application/json" - ], -]); - -$response = curl_exec($curl); -$err = curl_error($curl); - -curl_close($curl); - -if ($err) { - echo "cURL Error #:" . $err; -} else { - echo $response; -} -``` -```python Python -import http.client - -conn = http.client.HTTPSConnection("") - -payload = "{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }" - -headers = { 'content-type': "application/json" } - -conn.request("POST", "/{yourDomain}/oauth/revoke", payload, headers) - -res = conn.getresponse() -data = res.read() - -print(data.decode("utf-8")) -``` -```ruby Ruby -require 'uri' -require 'net/http' -require 'openssl' - -url = URI("https://{yourDomain}/oauth/revoke") - -http = Net::HTTP.new(url.host, url.port) -http.use_ssl = true -http.verify_mode = OpenSSL::SSL::VERIFY_NONE - -request = Net::HTTP::Post.new(url) -request["content-type"] = 'application/json' -request.body = "{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }" - -response = http.request(request) -puts response.read_body -``` -```swift Swift -import Foundation - -let headers = ["content-type": "application/json"] -let parameters = [ - "client_id": "{yourClientId}", - "client_secret": "{yourClientSecret}", - "token": "{yourRefreshToken}" -] as [String : Any] - -let postData = JSONSerialization.data(withJSONObject: parameters, options: []) - -let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/revoke")! as URL, - cachePolicy: .useProtocolCachePolicy, - timeoutInterval: 10.0) -request.httpMethod = "POST" -request.allHTTPHeaderFields = headers -request.httpBody = postData as Data - -let session = URLSession.shared -let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in - if (error != nil) { - print(error) - } else { - let httpResponse = response as? HTTPURLResponse - print(httpResponse) - } -}) - -dataTask.resume() -``` - - -Where: - -| Attribute | Description | -| --- | --- | -| `client_id`
Required | Your application's Client ID. The application should match the one the Refresh Token was issued for. | -| `client_secret` | Your application's Client Secret. Required for [confidential applications](/docs/get-started/applications/confidential-and-public-applications#confidential-applications). | -| `token`
Required | The Refresh Token you want to revoke. | +### Using the Auth0 Dashboard -The application should match the one for which the refresh token was issued. - -### Revoke tokens without the client secret +You can use the Auth0 Dashboard to revoke a user's authorized access to the application that issued the token. This renders the refresh token invalid, which is functionally identical to revoking the token itself. -For applications that cannot keep the client secret safe (such as native apps), the `/oauth/revoke` endpoint supports access without the client secret. However, the application itself must have the property `tokenEndpointAuthMethod` set to `none`. You can change the `tokenEndpointAuthMethod` value, either from the [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), or using the Management API. +1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users), and select the name of the user to view. +2. Select the **Authorized Applications** tab. This page lists all the applications to which the user has authorized access. +3. To revoke the user's access to an authorized application, and hence invalidate the refresh token, click **Revoke**. -If the request is valid, the refresh token is revoked, and the response is `HTTP 200`, with an empty response body. Otherwise, the response body contains the error code and description. +### Using the Authentication API -```json lines -{ - "error": "invalid_request|invalid_client", - "error_description": "Description of the error" - } -``` +You can use the Authentication API's [Revoke a refresh token endpoint](https://auth0.com/docs/api/authentication/revoke-refresh-token/revoke-refresh-token) to revoke a refresh token. -The possible responses are: +The endpoint supports access without the client secret for applications that cannot keep the it safe (such as native apps). The application itself must have the its [authentication method](/docs/get-started/applications/credentials) (`tokenEndpointAuthMethod`) set to none. -| HTTP Status | Description | -| --- | --- | -| 200 | The Refresh Token is revoked, does not exist, or was not issued to the application making the revocation request. The response body is empty. | -| 400 | The required parameters were not sent in the request (`"error": "invalid_request"`). | -| 401 | The request is not authorized (`"error": "invalid_client"`). Check that the application credentials (`client_id` and `client_secret`) are present in the request and hold valid values. | +When you make a request, the API first validates the application credentials and then verifies whether the token was issued to the application making the revocation request. If this validation fails, the request is refused, and the application is informed of the error. -## Use the Management API +Next, the API invalidates the token. The invalidation takes place immediately, and the token cannot be used again after the revocation. Each revocation request invalidates all the tokens that have been issued for the same authorization grant. -To revoke a refresh token using the Auth0 Management API, you need the `id` of the refresh token you wish to revoke. To obtain a list of existing refresh tokens, call the `/api/v2/device-credentials` [endpoint](https://auth0.com/docs/api/management/v2#!/Device_Credentials/get_device_credentials), specifying `type=refresh_token` and `user_id` with an access token containing `read:device_credentials` scope. To narrow the results, you can also specify the `client_id` associated with the token (if known). +For more information, including body parameters, response schemas, and code examples, read the [Revoke a refresh token endpoint](https://auth0.com/docs/api/authentication/revoke-refresh-token/revoke-refresh-token) Authentication API documentation. -export const codeExample11 = `GET https://{yourDomain}/api/v2/device-credentials? - type=refresh_token - &client_id= - &user_id= - - { - "Authorization": "Bearer {your_access_token}" - }`; +### Using the Management API device credentials endpoints - +To revoke a refresh token using the Auth0 Management API device credentials endpoints: -Response body: +1. Get the `id` of the refresh token you want to revoke using the [Retrieve device credentials endpoint](https://auth0.com/docs/api/management/v2/device-credentials/get-device-credentials). -```json lines -[ - { - "id": "dcr_dFJiaAxbEroQ5xxx", - "device_name": "my-device" // the value of 'device' provided in the /authorize call when creating the token - } - ] -``` + Specify `type=refresh_token` and a `user_id` with an access token containing the `read:device_credentials` scope. To narrow the results, you can also specify the `client_id` associated with the token (if known). -To revoke a refresh token, call the `/api/v2/device-credentials` endpoint with an access token containing `delete:device_credentials` scope and the value of ID obtained above: +2. Revoke the refresh token using the [Delete a device credential endpoint](https://auth0.com/docs/api/management/v2/device-credentials/delete-device-credentials-by-id). Specify an access token containing the `delete:device_credentials` scope and the refresh token ID. -export const codeExample12 = `DELETE https://{yourDomain}/api/v2/device-credentials/{id} +### Using the Management API refresh token endpoints + + +The Auth0 Management API refresh token endpoints are currently only available to customers on Enterprise plans. To learn more, read [Pricing](https://auth0.com/pricing). + -{ - "Authorization": "Bearer {your_access_token}" -}`; +The Management API's refresh token endpoints supercede the `/v2/device-credentials` resource endpoints with extended properties and bulk revocation operations. - +You can view or revoke a specific refresh token with the following endpoints: -The response will be `HTTP 204: The credential no longer exists.` +* View a refresh token information by ID with the [Get a refresh token endpoint](https://auth0.com/docs/api/management/v2/refresh-tokens/get-refresh-token) +* Revoke a refresh token by ID with the [Delete a refresh token endpoint](https://auth0.com/docs/api/management/v2/refresh-tokens/delete-refresh-token) +* List all refresh tokens for a user with the [Get refresh tokens for a user endpoint](https://auth0.com/docs/api/management/v2/users/get-refresh-tokens-for-user) +* Revoke all refresh tokens for a user with the [Delete refresh tokens for a user endpoint](https://auth0.com/docs/api/management/v2/users/delete-refresh-tokens-for-user) ## Considerations and limitations -With the [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow), the only way to force a device to reauthorize is to revoke the refresh token assigned to the device. See [Unlink Devices from Users](/docs/manage-users/user-accounts/unlink-devices-from-users) for details. The device will not be forced to reauthorize until the current access token expires and the application tries to use the revoked refresh token. +* With the [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow), the only way to force a device to reauthorize is to revoke the refresh token assigned to the device. The device will not be forced to reauthorize until the current access token expires and the application tries to use the revoked refresh token. For more information, read [Unlink Devices from Users](/docs/manage-users/user-accounts/unlink-devices-from-users). -When using [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation), if a previously invalidated token is used, the entire set of refresh tokens issued since that invalidated token was issued will immediately be revoked, requiring the end-user to re-authenticate. +* When using [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation), if a previously invalidated token is used, the entire set of refresh tokens issued since that invalidated token was issued will immediately be revoked, requiring the end-user to re-authenticate. -* Use the Authentication API `/oauth/revoke` [endpoint](https://auth0.com/docs/api/authentication#revoke-refresh-token) to revoke a refresh token. This endpoint does not delete the underlying grant. You can change this behavior to also delete the underlying grant in the Dashboard: [Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/#/tenant/advanced). Scroll to **Settings** and enable the **Refresh Token Revocation Deletes Grant** toggle. -* Use the Management API `/api/v2/device-credentials` [endpoint](https://auth0.com/docs/api/management/v2#!/Device_Credentials/get_device_credentials) to revoke refresh tokens configured for rotation. +* Refresh token revocation (`DELETE`) operations run asynchronously, and are eventually consistent. -## Learn more +* Refresh tokens issued on or after 21-09-2023 (22-02-2024 for tenants in the US-3 region) contain the session ID (`session_id`) property with the appropriate value. Refresh tokens issued before this date contain this property with a `null` value. -* [Get Refresh Tokens](/docs/secure/tokens/refresh-tokens/get-refresh-tokens) -* [Use Refresh Tokens](/docs/secure/tokens/refresh-tokens/use-refresh-tokens) -* [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation) -* [Configure Refresh Token Expiration](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration) +To learn more about refresh tokens limitations, read [Refresh Tokens limitations](/docs/secure/tokens/refresh-tokens). diff --git a/main/docs/secure/tokens/revoke-tokens.mdx b/main/docs/secure/tokens/revoke-tokens.mdx deleted file mode 100644 index 9f4d0bb9a5..0000000000 --- a/main/docs/secure/tokens/revoke-tokens.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -description: Describes how to use tokens to control user access. -title: Revoke Tokens ---- -Once issued, access tokens and ID tokens cannot be revoked in the same way as cookies with session IDs for server-side sessions. - -As a result, tokens should be issued for relatively short periods, and then [refreshed](/docs/secure/tokens/refresh-tokens) periodically if the user remains active. - -## Learn more - -* [Revoke Refresh Tokens](/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens) -* [Token Best Practices](/docs/secure/tokens/token-best-practices) \ No newline at end of file