diff --git a/docs/authentication.rst b/docs/authentication.rst
new file mode 100644
--- /dev/null
+++ b/docs/authentication.rst
@@ -0,0 +1,36 @@
+.. _authentication:
+
+Authentication
+==============
+
+This is a description of the authentication mechanism used in the deposit server.
+
+Keycloak
+--------
+
+Recent changes introduced `keycloak`_, an Open Source Identity and Access Management
+which is already used in other part of the swh stack.
+
+The authentication is plainly delegated to the swh keycloak instance. If keycloak
+authorizes the deposit client, the deposit further checks that the deposit client has
+the proper role "swh.deposit.api".
+
+If any issues arise during one of the authentication check, the client receives a 401
+response (unauthorized).
+
+.. figure:: images/deposit-authentication-keycloak.svg
+   :alt: Keycloak Authentication
+
+Basic
+-----
+
+The first implementation used basic authentication. The deposit storage backend has the
+responsibility to check the authentication credential sent by the deposit client. If
+authorized, the deposit client is authorized to continue its deposit. Otherwise, a 401
+response is returned to the client.
+
+.. figure:: images/deposit-authentication-basic.svg
+   :alt: Basic Authentication
+
+
+.. _keycloak: https://www.keycloak.org/
diff --git a/docs/images/deposit-authentication-basic.uml b/docs/images/deposit-authentication-basic.uml
new file mode 100644
--- /dev/null
+++ b/docs/images/deposit-authentication-basic.uml
@@ -0,0 +1,23 @@
+@startuml
+participant CLIENT as "SWORD client\n(eg. HAL)"
+participant DEPOSIT as "swh-deposit"
+participant AUTH_BACKEND as "deposit storage"
+
+activate CLIENT
+  activate DEPOSIT
+    activate AUTH_BACKEND
+
+      CLIENT ->> DEPOSIT: GET /1/<service-document>/
+
+      DEPOSIT ->> AUTH_BACKEND: check authentication
+      alt credentials mismatch or inexistent user
+        AUTH_BACKEND ->> DEPOSIT: return ko
+        DEPOSIT -->> CLIENT: return 401, Unauthorized
+      else credentials ok
+        AUTH_BACKEND ->> DEPOSIT: return deposit_client
+        DEPOSIT -->> CLIENT: return 200, <service-document>
+      end
+    deactivate CLIENT
+  deactivate DEPOSIT
+deactivate AUTH_BACKEND
+@enduml
diff --git a/docs/images/deposit-authentication-keycloak.uml b/docs/images/deposit-authentication-keycloak.uml
new file mode 100644
--- /dev/null
+++ b/docs/images/deposit-authentication-keycloak.uml
@@ -0,0 +1,30 @@
+@startuml
+participant CLIENT as "SWORD client\n(eg. HAL)"
+participant DEPOSIT as "swh-deposit"
+participant AUTH_BACKEND as "keycloak"
+
+activate CLIENT
+  activate DEPOSIT
+    activate AUTH_BACKEND
+
+      CLIENT ->> DEPOSIT: GET /1/<service-document>/
+
+      DEPOSIT ->> AUTH_BACKEND: forwards authentication to keycloak
+      alt credentials mismatch or inexistent user
+        AUTH_BACKEND ->> DEPOSIT: return 401, Unauthorized
+        DEPOSIT -->> CLIENT: return 401, Unauthorized
+      else credentials ok
+        AUTH_BACKEND ->> DEPOSIT: return oidc_profile
+        DEPOSIT ->> DEPOSIT: decodes oidc_profile, checks deposit user roles
+
+        alt no role matches 'swh.deposit.api'
+          DEPOSIT -->> CLIENT: return 401, Unauthorized
+        else at least one role matches 'swh.deposit.api'
+          DEPOSIT -->> CLIENT: return 200, <service-document>
+        end
+
+      end
+    deactivate CLIENT
+  deactivate DEPOSIT
+deactivate AUTH_BACKEND
+@enduml
diff --git a/docs/index.rst b/docs/index.rst
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -23,3 +23,4 @@
 
    cli
    /apidoc/swh.deposit
+   authentication.rst