diff --git a/docs/api/index.rst b/docs/api/index.rst --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -11,3 +11,4 @@ api-documentation metadata use-cases + register-account diff --git a/docs/api/register-account.rst b/docs/api/register-account.rst new file mode 100644 --- /dev/null +++ b/docs/api/register-account.rst @@ -0,0 +1,45 @@ +.. _swh-deposit-register-account: + +.. admonition:: Intended audience + :class: important + + - deposit clients + - sysadm staff members + +Register account +================ + +.. _swh-deposit-register-account-as-deposit-client: + +As a deposit client +------------------- + +For this, as a client, you need to register an account on the swh keycloak `production +`_ +or `staging +`_ +instance. + +.. _swh-deposit-register-account-as-sysadm: + +As a sysadm +----------- + + +1. Retrieve the deposit client login (through email exchange or any other media). + +2. Require a :ref:`provider url ` from the deposit + client (through email exchange or any other media). + +3. Within the keycloak `production instance `_ or `staging + instance `_, add the `swh.deposit.api` role to the deposit + client login. + +4. Create an :ref:`associated deposit collection + ` in the deposit instance. + +5. Create :ref:`a deposit client ` with the + provider url in the deposit instance. + +6. To ensure everything is ok, ask the deposit client to check they can access at least + the service document iri (authenticated). diff --git a/docs/api/user-manual.rst b/docs/api/user-manual.rst --- a/docs/api/user-manual.rst +++ b/docs/api/user-manual.rst @@ -10,8 +10,8 @@ Requirements ------------ -You need to have an account on the Software Heritage deposit application to be -able to use the service. +You need to :ref:`have an account on the Software Heritage deposit application +` to be able to use the service. Please `contact the Software Heritage team `_ for more information on how to get access to this service. diff --git a/docs/internals/prod-environment.rst b/docs/internals/prod-environment.rst --- a/docs/internals/prod-environment.rst +++ b/docs/internals/prod-environment.rst @@ -53,6 +53,8 @@ sudo django-admin migrate --settings=swh.deposit.settings.production +.. _swh-deposit-add-client-and-collection: + Add client and collection ------------------------- diff --git a/docs/specs/protocol-reference.rst b/docs/specs/protocol-reference.rst --- a/docs/specs/protocol-reference.rst +++ b/docs/specs/protocol-reference.rst @@ -74,6 +74,8 @@ including a link to download its source code. This is not a technical requirement, but it improves discoverability. +.. _swh-deposit-provider-url-definition: + Clients may not submit arbitrary URLs; the server will check the URLs they submit belongs to a "namespace" they own, known as the ``provider_url`` of the client. For example, if a client has their ``provider_url`` set to ``https://example.org/foo/`` they