Document new GET endpoint

csrf-tokens.md

@@ -4,8 +4,22 @@
 All modifying requests (`POST`, `PUT`, `PATCH`, `DELETE`, etc) **require** that the client send a valid CSRF token
 in the `X-XSRF-TOKEN` header, otherwise a `403 Forbidden` error will occur. 
 
-The CSRF token is sent to the client in a prior request (often a `GET`) and may be changed during your session at any time.
-See [How does CSRF protection work in DSpace?](#how-does-csrf-protection-work-in-dspace) below for more details.
+## How to obtain/reset a CSRF token?
+
+The CSRF token is sent automatically to the client in a prior request (often a `GET`) and may be changed during your session at any time. The client MUST watch for changes to the CSRF token in every request (although in practice the token should primarily only change during login/logout or authentication refresh, etc)
+See [How does CSRF protection work in DSpace REST API?](#how-does-csrf-protection-work-in-dspace-rest-api) below for more details.
+
+A `GET` endpoint is also available to force a CSRF token refresh. See below.
+
+### GET /api/security/csrf
+
+Provides a new CSRF Token to the client for usage in later requests. This endpoint SHOULD BE USED SPARINGLY as every call to this endpoint will create a new CSRF token. The DSpace REST API automatically manages CSRF tokens and sends them back to the client _only when the token needs to be changed_ (e.g. on login/logout, etc). Using this endpoint to refresh CSRF tokens frequently may result in unexpected behaviors or even performance issues. The primary purpose of this endpoint is to obtain the *first* CSRF token (if not yet sent by the REST API).
+
+This endpoint returns an empty response with the newly generated CSRF Token in the `DSPACE-XSRF-TOKEN` HTTP Header. It will also save this CSRF Token to the `DSPACE-XSRF-COOKIE` server-side Cookie, for later verification. See [How does CSRF protection work in DSpace REST API?](#how-does-csrf-protection-work-in-dspace-rest-api) below for more details about this header and cookie.
+
+Error codes:
+* 204 No Content - if the operation succeeded no body will be returned. The new token will be returned in the CSRF header and cookie.
+* 403 Forbidden - This endpoint will only respond to GET requests. All other requests types (POST/PUT) will return a 403.
 
 ## What is CSRF and why is this necessary?