@spec delete_api_key() :: DSpace.API.Operation.t()

Deletes an API key.

Executing this operation invalidates the currently authenticated user's API key ("machine token").

@spec fetch_api_key() :: DSpace.API.Operation.t()

Fetches an API key for the currently authenticated user.

In DSpace-CRIS-speak the API key is called "machine token". The returned token is valid until manually revoked using delete_api_key/0.

@spec fetch_short_lived_token() :: DSpace.API.Operation.t()

Fetches a short-lived access token from the API.

Short-lived tokens are used for operations like downloading restricted files.

@spec login(binary(), binary()) :: DSpace.API.Operation.t()

Authenticates with the DSpace API using the provided credentials.

Returns an operation to get an access token. Executing this operation will fetch a CSRF token from the API first if none is configured in the client, since that is a prerequisite for hitting the login endpoint.

Managing token lifecycle (checking expiry, deciding when to refresh) is the responsibility of the consuming application. The token is a JWT and contains an exp claim. See refresh_access_token/0.

@spec logout() :: DSpace.API.Operation.t()

Invalidates all access tokens associated with the user's current session.

@spec refresh_access_token() :: DSpace.API.Operation.t()

Retrieves a fresh access token from the API.

Executing this operation returns a freshly issued token with an extended expiration time.

@spec refresh_csrf_token() :: DSpace.API.Operation.t()

Retrieves a fresh CSRF token from the API.

This is not a "real" refresh on DSpace < 7.6.2 where the /api/security/csrf endpoint doesn't exist and this function uses the /api/authn/status endpoint instead.

@spec status() :: DSpace.API.Operation.t()

Verifies if the client is authenticated with the DSpace API.

Performing this operation will return {:ok, true} or {:ok, false}.

@spec tokens_from_response(DSpace.API.HTTP.Response.t()) ::
  {:ok, {binary(), binary()}} | {:error, DSpace.API.Error.t()}

Extracts the access token and CSRF token from an API response.

Returns the tokens or an error.