API Access to ChekRite

ChekRite plays well with others. We allow your application to securely access ChekRite to share information both ways. However, before you can do this, you need to do some basic setup first.

You must have Company Administrator Access to the portal to undertake these steps. If you don't have access to the portal then contact your ChekRite Administrator to get this access.

ChekRite uses the OAuth 2.0 protocol for accessing our application.

Registering Your Application

First, developers building applications that need to interact with ChekRite application's API will need to register their application with ours by creating a "client". Typically, this consists of providing the name of their application and a URL that our application can redirect to after users approve their request for authorization. You can do so by logging in https://api.chekrite.com/login and click on "Create New Client" from the dashboard, then enter the name and redirect url fields and click "Create". After that, please note down the Client ID and Secret generated.

Requesting an Authorisation Code

Once a client has been created, developers may use their Client ID and secret to request an authorization code and access token from our application. First, the consuming application should make a redirect request to our application's /oauth/authorize route like so:

Route::get('/redirect', function (Request $request) {
    $request->session()->put('state', $state = Str::random(40));

    $query = http_build_query([
        'client_id' => 'client-id',
        'redirect_uri' => 'http://example.com/callback',
        'response_type' => 'code',
        'scope' => '',
        'state' => $state,
    ]);

    return redirect('http://your-app.com/oauth/authorize?'.$query);});

PHP code for illustration

When receiving authorization requests, Chekrite will automatically display a template to the user allowing them to approve or deny the authorization request. If they approve the request, they will be redirected back to the redirect_uri that was specified by the consuming application. The redirect_uri must match the redirect URL that was specified when the client was created. If the user approves the authorization request, they will be redirected back to the consuming application. The consumer should first verify the state parameter against the value that was stored prior to the redirect. If the state parameter matches the consumer should issue a POST request to ChekRite application to request an access token. The request should include the authorization code that was issued by ChekRite when the user approved the authorization request. In this example, we'll use the Guzzle HTTP library to make the POST request:

Route::get('/callback', function (Request $request) {
    $state = $request->session()->pull('state');

    throw_unless(
        strlen($state) > 0 && $state === $request->state,
        InvalidArgumentException::class
    );

    $http = new GuzzleHttp\Client;

    $response = $http->post('http://your-app.com/oauth/token', [
        'form_params' => [
            'grant_type' => 'authorization_code',
            'client_id' => 'client-id',
            'client_secret' => 'client-secret',
            'redirect_uri' => 'http://example.com/callback',
            'code' => $request->code,
        ],
    ]);

    return json_decode((string) $response->getBody(), true);});

This /oauth/token route will return a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires.With the access_token, consuming application can now start calling various endpoints offered by ChekRite API. As ChekRite issues short-lived access tokens, users will need to refresh their access tokens via the refresh token that was provided to them when the access token was issued. In this example, we'll use the Guzzle HTTP library to refresh the token:

$http = new GuzzleHttp\Client;

$response = $http->post('http://your-app.com/oauth/token', [
    'form_params' => [
        'grant_type' => 'refresh_token',
        'refresh_token' => 'the-refresh-token',
        'client_id' => 'client-id',
        'client_secret' => 'client-secret',
        'scope' => '',
    ],]);

return json_decode((string) $response->getBody(), true);

This /oauth/token route will return a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires.

Implicit Grant Tokens

The implicit grant is similar to the authorization code grant; however, the token is returned to the client without exchanging an authorization code. This grant is most commonly used for JavaScript or mobile applications where the client credentials can't be securely stored. To enable the grant, call the enableImplicitGrant method in your AuthServiceProvider:

/**
 * Register any authentication / authorization services.
 *
 * @return void
 */public function boot(){
    $this->registerPolicies();

    Passport::routes();

    Passport::enableImplicitGrant();}

Once a grant has been enabled, developers may use their client ID to request an access token from your application. The consuming application should make a redirect request to your application's /oauth/authorize route like so:

Route::get('/redirect', function (Request $request) {
    $request->session()->put('state', $state = Str::random(40));

    $query = http_build_query([
        'client_id' => 'client-id',
        'redirect_uri' => 'http://example.com/callback',
        'response_type' => 'token',
        'scope' => '',
        'state' => $state,
    ]);

    return redirect('http://your-app.com/oauth/authorize?'.$query);});

API Documentation

ChekRite has fully documented API's that you can access. We use Swagger to document these API's in industry standard formats.

To access the ChekRite API Documentation you will need to have a ChekRite Portal account. Then, head over to api.chekrite.com and sign in to access the documentation.