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

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.

Request Headers:  

• Content-Type – the request’s content-type has to be passed in this header
• Accept – the response content type depends on Accept header
• Authorization – Basic YnV0bGVyOmJ1dGxlcg== (fixed string)

Form Parameters:  

• grant_type – Type of grant. Should be set to password
• username – Username
• password – Password

Status Codes:

• 200 OK – No error
• 401 Unauthorized – Not authorized

Response JSON Object:  

• access_token (string) – Access token string
• expires_in (integer) – Number of seconds till which this token will be valid

Example request:

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:

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:

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