.. _epp-login-command:

Login
=====

Login command authenticates the client for the rest of the TCP session.
It follows standard EPP and is not extended or restricted in any way.

Client request
--------------

Parameters:

``clID``
    Identification (client ID) assigned to the registrar for the EPP account.
    Client ID and password are chosen by the Registry.

    .. note::

       Please, note that ``clID`` is case-sensitive in a login command.

``pw``
    It contains the password for the EPP account.

``<newPW>``
    *(OPTIONAL)* element can be provided to change the password of Your EPP account.

    .. note::

       An empty ``<newPW/>`` element would cause schema validation to fail - ``newPW`` should contain a valid new password if present.

``version``
    the EPP version to use (only "1.0" is supported currently)

``lang``
    two-letter language code the server response messages will be translated into (in lowercase, currently only ``en`` is supported).

``objURI``
    lists namespace URIs of standard RFC-defined EPP services to be used
    (should contain at least ``urn:ietf:params:xml:ns:domain-1.0`` and ``urn:ietf:params:xml:ns:contact-1.0``).

    ``urn:ietf:params:xml:ns:host-1.0`` is not supported and would result in error.

``svcExtension``
    may contain none, one or more ``extURI`` elements with namespace URIs identifying EPP extensions to be used.
    Although it may be left empty, without the following extensions there isn't much that can be done:

    * ``http://www.nic.lv/epp/schema/lvcontact-ext-1.0`` is required to work with contact objects - registrants from Latvia;
    * ``http://www.nic.lv/epp/schema/lvdomain-ext-1.0`` enables the client to work with domains, included in the current bill.

    We support also standard ``urn:ietf:params:xml:ns:secDNS-1.1`` extension to work with DNSSEC-signed domain names.


Values of ``version``, ``lang``, ``objURI`` and ``extURI`` should be chosen from
the values offered by the server in :ref:`greeting response <epp-hello-command>` when the connection was started.

The session will be closed if more than 5 failed login attempts happen in a row.

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0 epp-1.0.xsd">

      <command>
        <login>
          <clID>niceppuser</clID>
          <pw>12345678</pw>
          <newPW>AbCdEfG1</newPW>

          <options>
            <version>1.0</version>
            <lang>en</lang>
          </options>
          <svcs>
            <objURI>urn:ietf:params:xml:ns:domain-1.0</objURI>
            <objURI>urn:ietf:params:xml:ns:contact-1.0</objURI>
            <svcExtension>
              <extURI>http://www.nic.lv/epp/schema/lvdomain-ext-1.0</extURI>
              <extURI>http://www.nic.lv/epp/schema/lvcontact-ext-1.0</extURI>
            </svcExtension>
          </svcs>
        </login>
        <clTRID>9a4I5Rd0QOaGcPJbsog5</clTRID>
      </command>
    </epp>

Server response
---------------

The server responds to a ``<login>`` command with a result code of 1000 ("Login successful")
and gives access to all commands for viewing and transforming domain names and other registry objects the client manages.

Response may include a ``<msgQ>`` element with ``count`` and ``id`` attributes,
containing number of unread :ref:`service messages <epp-msg-queue>` waiting for the registrar to dequeue
and ``id`` of the next message to be returned by :ref:`<poll> <epp-poll-request>` request.

Following errors may occur:

* ``2005`` if ``newPW`` given but the new password was not valid
* ``2102`` when unsupported protocol option is chosen (not offered in server :ref:`greeting response <epp-greeting>`)
* ``2200`` if the wrong combination of ``clID``/``pw`` was given
* ``2501`` when too many unsuccessful authentication attempts have been made
* ``2502`` if the session limit is exceeded for the registrar  (please, close some of the oldest ones before attempting to start a new one)