Skip to content
21 changes: 13 additions & 8 deletions proposals/4254-oauth2-revocation.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,17 @@ The discovery of the above metadata is out of scope for this MSC, and is current

### Token revocation

When a user wants to log out from a client, the client should revoke either its access token or refresh token by making a POST request to the revocation endpoint as described in [RFC7009].
When a user wants to log out from a client, the client SHOULD revoke either its access token or refresh token by making a POST request to the revocation endpoint as described in [RFC7009].

The server must revoke both the access token and refresh token associated with the token provided in the request.
The server MUST revoke both the access token and refresh token associated with the token provided in the request.

The request includes:
- The `token` parameter containing either the access token or refresh token to revoke
- Optionally, the `token_type_hint` parameter, with either the `access_token` or `refresh_token` value. If provided, the server must use this value to determine which token to revoke
- The `client_id` obtained during client registration
The request includes the following parameters, encoded as `application/x-www-form-urlencoded`:

- `token`: This parameter MUST contain either the access token or the refresh token to be revoked.
- `token_type_hint`: This parameter is OPTIONAL, and if present, MUST have a value of either `access_token` or `refresh_token`. The server MAY use this value to optimize the token lookup process
- `client_id`: The client identifier obtained during client registration.

If the `client_id` is not provided, or does not match the client associated with the token, the server SHOULD still revoke the token. The server MAY also warn the user that one of their sessions may be compromised in this scenario.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not entirely following why a server would want to warn if one of the sessions is compromised if no client_id is provided. A sentence or two of rationale might help here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've explained that better in cd239ce


#### Sample flow

Expand Down Expand Up @@ -61,9 +64,11 @@ HTTP/1.1 200 OK

### Handling errors

The server may return an error response as defined in [RFC7009]. The client should handle these errors appropriately:
The server may return an error response as defined in [RFC7009]. Note that RFC7009 mandates a [RFC6749 error response](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) rather than a Matrix standard error response.

The client should handle these errors appropriately:

- If the token is already revoked, the server returns a 200 OK response
- If the token is already revoked or invalid, the server returns a 200 OK response
- If the client is not authorized to revoke the token, the server returns a 401 Unauthorized response
- For other errors, the server returns a 400 Bad Request response with error details

Expand Down