Authentication

Implementing OAuth 2.0

Intro to OAuth

When people talk about OAuth, they typically mean OAuth 2.0: an authorization framework that describes how unrelated services can grant access to resources. It’s an open standard used by apps, APIs, and other services over HTTPS.

OAuth decouples authentication from authorization, by relying on a third party to grant an access token. Doing this reduces your attack surface since your client secret is not required to access certain resources. The Authorization Server authenticates a user and approves their access to a resource by providing a temporary authorization code. A token can then be requested using your credentials along with this authorization code.

OAuth2.0 specification is outlined in RFC 6479

OAuth Process Flow

Process descriptions

1.1 Send your YUMBI Gateway-issued client ID and client secret in the Request Access Token call to retrieve an access token.

1.2 Your client ID and client secret are verified.

1.3 The access token is returned in the response.

2.1 Use the access token to make requests to the YUMBI Gateway API.

Steps to implement OAuth

First, you will need to call Request Access Token to obtain a client access token by sending the client ID and client secret to the authorisation server to retrieve an access token (YUMBI Gateway provides you with the client ID and client secret when you are onboarded).

You can do this by sending a POST request:

POST /oauth2/token HTTP/1.1
Host:   https://auth.yumbi.com
Content-Type: application/json
{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "grant_type": "client_credentials"
}

The client_id and client_secret properties should contain your client id and client secret respectively. They will be validated to check that you can get an access token. The grant_type determines which authentication flow should be used. When initiating this call, always set the value of grant_type as client_credentials.

The access token will be returned in the response, and will look like this:

HTTP/1.1 200 OK

{
    "access_token": "eyJraWQiOiJYREtWbVlLK1dcL0E0Q0M0U0FpOGxUeU51a2gzTUpqcHlzQmhCcUZ0YnZOTT0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxZmRkOGM3MjJvaGozMHFtaDFhMDc2bnM0ZCIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiaXBndy1jbnBcL2F1dGhvcmlzZSBpcGd3XC9zZXNzaW9uIGlwZ3dcL3RyYW5zYWN0aW9uIGlwZ3ctY25wXC9yZXZlcnNlIGlwZ3ctY25wXC9zZXR0bGUgaXBndy0zZHNcL2xvb2t1cCBpcGd3LWNucFwvcmVmdW5kIGlwZ3dcL2NvbmZpZyBpcGd3XC9pbnRlbnQgaXBndy0zZHNcL3ZhbGlkYXRlIiwiYXV0aF90aW1lIjoxNjY3ODE3ODU0LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAuZXUtd2VzdC0xLmFtYXpvbmF3cy5jb21cL2V1LXdlc3QtMV9lY1lXckJrOTkiLCJleHAiOjE2Njc4MjE0NTQsImlhdCI6MTY2NzgxNzg1NCwidmVyc2lvbiI6MiwianRpIjoiYjg2YmM2YWMtYzM0Mi00MDA4LTk2YWQtOTk3NjdiNGE2MTE4IiwiY2xpZW50X2lkIjoiMWZkZDhjNzIyb2hqMzBxbWgxYTA3Nm5zNGQifQ.cqdqe_l9C1P4Gsv9QCmydwgNS6fXBqLaXSGC7USMGQXcyd8AtAsvEvDrCwWwclYthd4QBbPl9eB1T0ojisbr3bQ-cPOZGRl411VWUhIyr1Anh_Kpylq-FfDn4CqWoq-E9d4XGI4x-XUlRm1nYjBa9i_klptGRKUgSpT4ivcG6bGz0HC5Pm8LZZZOrSkuzJu8n4xWSBH8HcIeKYLTfSVsF8l0DoJL_rns9m9xbGLr92LVoufpcmCLt41aVPQYTuz72vzLprZP21hqbK0CZSyLz20r-39mXP-_fagREq781jpOJ5An9eYPs34dP-qIAvegRT7YotrBkSWLBfjEJDCNVw",
    "expires_in": 3600,
    "token_type": "Bearer"
}

All API calls to the YUMBI Gateway API must be performed using a valid access token as the header authorisation parameter, and would look like this:

curl https://gateway.yumbi.com/api/v1/webhooks -H "Authorization: Bearer {access_token}"