.. _authentication:

API Authentication
=========================

.. contents:: Topics

Integration Identifier and Secret
------------------------

.. _integration_identifier:

All API calls to Paytronix require that an integration identifier and secret, essentially a username and password for your integration, be sent as part of the request. These values must be sent with every API call in an HTTP Basic authorization header (formatted as the base64-encoded representation of ``identifier:secret``). See `the wikipedia entry on HTTP basic authentication <http://en.wikipedia.org/wiki/Basic_access_authentication>`_ if you are not familiar with this form of authentication.

The identifier and secret values will be provided by the Paytronix integrations team once the integration process has begun. The integration identifier uniquely identifies a single application, and must not be shared between separate software systems. As these credentials allow the holder to act on behalf of your application it would be extremely bad if you were to lose control of them, so please be extremely cautious when handling them. In particular, please do not send the secret value in emails, Slack messages, or the like.

.. _anonymous_auth:

Anonymous authentication
------------------------

Some endpoints do not required additional authentication, however they might still be rejected for security reasons if the particular type of request has been disabled for the merchant or program.  No additional parameters are required for anonymous authentication.

.. http:jsonentity:: AnonymousAuthentication

   :jsonparam String authentication: *(required)* ``anonymous``

.. _email_auth:

Guest email authentication
--------------------------

To authenticate using a registered guest's email address and card template code, use the ``email`` authentication method.

.. http:jsonentity:: GuestEmailAuthentication

   :jsonparam String authentication: *(required)* ``email``
   :jsonparam Integer merchantId: *(required)* Paytronix-assigned identifier for the merchant.
   :jsonparam String email: *(required)* The guest's email address that is associated with a Paytronix account.
   :jsonparam Integer cardTemplateCode: *(required)* The card template of the guest's Paytronix account.

.. _b2b_auth:

B2B authentication
------------------

For server to server integrations as a partner of Paytronix (i.e. not a mobile app or similar) use the ``b2b`` authentication method, providing the username and password assigned by Paytronix client services.

.. http:jsonentity:: B2BAuthentication

   :jsonparam String authentication: *(required)* ``b2b``
   :jsonparam String Authorization: *(required)* A HTTP ``Basic`` authorization header containing ``username:password`` that's been Base64 encoded. See `the wikipedia entry on HTTP basic authentication <http://en.wikipedia.org/wiki/Basic_access_authentication>`_.

.. _oauth_auth:

OAuth authentication
--------------------

Once an access token has been negotiated with Paytronix for a guest, use the ``oauth`` authentication method to use the access token when accessing endpoints.

See :ref:`oauth_auth` and :ref:`oauth_service`.

.. http:jsonentity:: OAuthAuthentication

   :jsonparam Integer merchantId: *(required)* Paytronix-assigned identifier for the merchant.
   :jsonparam String access_token: *(required)* OAuth access token received from the OAuth service.
   :jsonparam String client_id: *(required unless given in ``Authorization`` header)* OAuth client identifier, sometimes called an integration identifier. If using both B2B and OAuth, usually the ``client_id`` is the same as the B2B username.
   :jsonparam String client_secret: *(required unless given in ``Authorization`` header)* OAuth client secret password. If using both B2B and OAuth, usually the ``client_id`` is the same as the B2B password. **Note:** ``client_secret`` cannot be used in ``GET`` requests, instead use the ``Authorization`` header.
   :jsonparam String Authorization: *(required)* A HTTP ``Basic`` authorization header containing ``client_id:client_secret`` that's been Base64 encoded. See `the wikipedia entry on HTTP basic authentication <http://en.wikipedia.org/wiki/Basic_access_authentication>`_. Using the ``Authorization`` header is preferable to ``client_id`` and ``client_secret``, as it works for ``GET``, ``DELETE``, ``POST``, and ``PUT`` requests equivalently.