Introduction
============

Many datasets at GEOFON contain *restricted* data.
By this, we mean that access is limited to those people authorised by the data provider, typically, the PI(s).
Who the PI authorises is their choice; we can help you request access if desired.
Sometime an entire seismic network is restricted; other times only a few stations or channels may be restricted.

To ensure that we do not serve restricted data to unauthorised people,
we must ask you to authenticate to our service - that is, present some
credentials which identify who you are.
You may use our services unauthenticated, but then we can only provide
you with open (unrestricted) data.

We use a token-based system.
The token is a cookie-like piece of data, containing identifying information, such as your name.

#. The token is for your personal use, and only one is needed for all the different data sets at GEOFON that you may be entitled to access.
#. The token is digitally signed by a trusted party [#foot-trusted]_,
   and has a fixed validity period.
#. You present the token to the service's /auth method, at a URL such as
   https://geofon.gfz-potsdam.de/fdsnws/dataselect/1/auth

#. If the digital signature is valid, a temporary account for `/queryauth` is created.
#. You then use the `/queryauth` method to request data, instead of the usual `/query` method.

When a token expires, you simply go back to the trusted party to generate a new one.

Historically, our Arclink service asked for your user name
(typically, your e-mail address),
and served data which was encrypted using a password which had been sent
to you previously.
This approach is not possible using FDSN web services (`fdsnws-dataselect`, etc).

FDSNWS authentication is also supported by the
`latest version of WebDC 3 <http://eida.gfz-potsdam.de/webdc3/?fdsnws=enabled>`_.

On the next pages we show you:

1. How to obtain credentials (via a token).
2. How to use these to request data.

For advanced users, we provide some additional details
in :ref:`sec-auth-details`.
Information about the personal data we retain is also there.

.. note::
     We expect that there may be problems,
     misunderstandings, and gaps in the documentation.
     In case of difficulties, don't hesitate to contact us.
     The :ref:`sec-auth-faq` section may help you.


.. [#foot-trusted] What is a trusted party?
    Today, tokens are provided by the EIDA Authentication Service (EAS) at
    `https://geofon.gfz-potsdam.de/eas` .
    In the background we use a service which
    could act as a proxy to eduGAIN, in the case that your home institution allows
    it, or lets you create a local account. An eduGAIN Identity Provider
    serves as the trusted party - you give it, not us, your credentials,
    and it provides a token which we accept as proof of your
    identity. Both we and you trust the eduGAIN infrastructure
    to do this correctly.