Authentication
##############

Authentication is mandatory for all APIs. GreyMatter APIs support oauth token
based authentication. A pre-shared username and password is required to fetch
the token.

The authentication workflow is like this:

1. Get authentication token from oauth endpoint
2. Use the token in all API requests
3. When token expires, handle the 401 response, and fetch a new token

Fetch an oauth token
********************

.. http:post:: /api-gateway/auth-service/platform-auth/oauth/token

   API to fetch a an oauth token. Username/Password can be passed either as URL
   parameters, or (urlencoded) form parameters. The Content-Type header has to
   be set accordingly.

   :reqheader Content-Type: the request's content-type has to be passed in this
                            header
   :reqheader Accept: the response content type depends on
                      :mailheader:`Accept` header
   :reqheader Authorization: ``Basic YnV0bGVyOmJ1dGxlcg==`` (fixed string)

   :fparam grant_type: Type of grant. Should be set to ``password``
   :fparam username: Username
   :fparam password: Password

   :statuscode 200: No error
   :statuscode 401: Not authorized

   :>json string access_token: Access token string
   :>json integer expires_in: Number of seconds till which this token will be
                              valid

   **Example request**:

   .. sourcecode:: http

      POST /api-gateway/auth-service/platform-auth/oauth/token HTTP/1.1
      Host: example.com
      Content-Type: application/x-www-form-urlencoded
      Accept: application/json, text/javascript
      Authorization: Basic YnV0bGVyOmJ1dGxlcg==

      grant_type=password&username=upstream&password=upstream

   **Example Response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json;charset=UTF-8

      {
          "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJvcGVuaWQiXSwiZXhwIjoxNTI2MjQyOTkxLCJqdGkiOiIwZTJmZWVmNy05NTNmLTRhYjQtYjJhMi0wMWMwNWFiMDFjYTUiLCJjbGllbnRfaWQiOiJidXRsZXIifQ.bpTUDcegYcIwY4ABLpaJk9yns0KKatOG3wXEhdWVWLbN1lZ_jxMsQxZlvn-gFtcZPjsnqQrGsSdKH3APVSdemr61hkLZDmeTZn62JmXXADO-rfGOcdVXUdmN8q5hxqqn93XV-zKk81dbnqD_WXKCLp6k6zTkSJcqXOANJ53K80RGxJgct_KZwgwJRHGE1CHKUkg_9675D2os5NtnC7Q1JSMhafrPvqvfy7IjijjnEJ4iqPCAg9fCgmbpNIMZrcorAdkxUjKglPQtumB3UK8Qp6ENjeahqKv9sk5gki9u_tXAWnLosYKlD7yrWAJc__Sm84KShVMh72JMT6QdOVh8iA",
          "token_type": "bearer",
          "refresh_token": "another_large_token_string",
          "expires_in": 43199,
          "scope": "openid",
          "user_id": -1,
          "jti": "dd346860-bcf3-420b-b484-575b62c333be"
      }

Use authentication token in API calls
*************************************

For using the oauth token acquired above, the it has to be sent in the following
HTTP header in all API calls::

  Authorization: Bearer <access_token>

Accept and Content-Type headers must also be passed according to the API. In
most GreyMatter APIs, both of these should be set to ``application/json``.

**Example request**:

.. sourcecode:: http

   GET /api-gateway/mdm-service/wms-masterdata/catalog HTTP/1.1
   Host: example.com
   Content-Type: application/json
   Accept: application/json
   Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJvcGVuaWQiXSwiZXhwIjoxNTI2MjQyOTkxLCJqdGkiOiIwZTJmZWVmNy05NTNmLTRhYjQtYjJhMi0wMWMwNWFiMDFjYTUiLCJjbGllbnRfaWQiOiJidXRsZXIifQ.bpTUDcegYcIwY4ABLpaJk9yns0KKatOG3wXEhdWVWLbN1lZ_jxMsQxZlvn-gFtcZPjsnqQrGsSdKH3APVSdemr61hkLZDmeTZn62JmXXADO-rfGOcdVXUdmN8q5hxqqn93XV-zKk81dbnqD_WXKCLp6k6zTkSJcqXOANJ53K80RGxJgct_KZwgwJRHGE1CHKUkg_9675D2os5NtnC7Q1JSMhafrPvqvfy7IjijjnEJ4iqPCAg9fCgmbpNIMZrcorAdkxUjKglPQtumB3UK8Qp6ENjeahqKv9sk5gki9u_tXAWnLosYKlD7yrWAJc__Sm84KShVMh72JMT6QdOVh8iA