Authentication

The client is making a request on behalf of the organization user. We use OAuth2 to authenticate all API requests. Read an introduction to the OAuth2 protocol here. Below is a quick overview how to use OAuth2 with HappyrMatch API.

Step 1 - Getting the authorization code

To authenticate a user, redirect them to https://api.happyrmatch.com/oauth/authorize with the following query parameters:

  • response_type - with the value code
  • client_id - with your client identifier
  • redirect_uri - with the client redirect URI. This parameter is optional and defaults to a pre-registered redirect URI.
  • scope - a space delimited list of scopes
  • state - with a CSRF token. This parameter is optional but highly recommended. You should store the value of the CSRF token in the user’s session to be validated when they return.

If the user accepts that the API client can make requests on their behalf, they will be redirected back to redirect_uri with the following query parameters:

  • code - with the authorization code
  • state - with the state parameter sent in the original request. You should compare this value with the value stored in the user’s session to ensure the authorization code obtained is in response to requests made by this client rather than another client application.

Step 2 - Getting the access token

The client sends a POST request to https://api.happyrmatch.com/oauth/token and you get the access token back in the respose.

Request

POST /oauth/token
Host: api.happyrmatch.com
Content-Type: application/x-www-form-urlencoded

client_id=abc&client_secret=def&grant_type=authorization_code&redirect_uri=https://same.as/before&code=xxx
  • grant_type - with the value of authorization_code
  • client_id - with the client identifier
  • client_secret - with the client secret
  • redirect_uri - with the same redirect URI the user was redirect back to
  • code - with the authorization code from the query string

Response

HTTP/1.0 200 OK
Cache-Control: no-cache, private
Content-Type:  application/json; charset=UTF-8
Date:          Wed, 25 Sep 2019 13:33:29 GMT

{
    "token_type": "Bearer",
    "expires_in": 7200,
    "access_token": "xxxxx",
    "refresh_token": "yyyyy"
}

Step 3 - Refresh the access token

When you have used the access token for a few hours, it will expire. To obtain a new access token you would need to use the refresh_token. 

POST /oauth/token
Host: api.happyrmatch.com
Content-Type: application/x-www-form-urlencoded

client_id=abc&client_secret=def&grant_type=refresh_token&refresh_token=yyyyy

Response

HTTP/1.0 200 OK
Cache-Control: no-cache, private
Content-Type:  application/json; charset=UTF-8
Date:          Wed, 25 Sep 2019 13:33:29 GMT

{
    "token_type": "Bearer",
    "expires_in": 7200,
    "access_token": "zzzzz",
    "refresh_token": "vvvvv"
}