API

• Introduction
• Configuration
• Defining API Route
• Accessing API Route
  • From JavaScript Application
• Scopes
• Checking Scopes
  • Via Middleware
  • Via TokenCan Method

Introduction

Larakits comes with API development support. It allows your user to create API tokens for authenticating your API routes. Optionally, you can register token scopes from where your user can determine which action this API token can perform.

If you check configs/auth.php file, you will see larakits as custom API authentication guard. This guard allows you to access your API routes without passing API token from your JavaScript Application. If you are requesting API routes from SDK, make sure you are passing valid API token.

Configuration

By default, API support is disabled for your application. You will not see any link for the API pages on /settings page. To enable API support, you must set TRUE for the $api property of App\Providers\LarakitsServiceProvider class.

Defining API Route

Defining API route is straightforward. If you missed Laravel docs for API authentication, here an example for you:

use Illuminate\Http\Request;

Route::middleware('auth:api')->get('/user', function(Request $request) {
	return $request->user();
});

In the example, /user route is defined with auth:api middleware. The auth middleware will ensure that non-authenticate user can’t access the route. If you want to create route for non-authenticate user, leave the auth:api middleware.

Accessing API Route

Once API route is defined, user can access the API route by their API token. They have to pass their API token via api_token query string or as a Bearer token in the Authorization header of the request.

From JavaScript Application

When you are building your application that shares your API between your JavaScript application and SDK, your JavaScript application have to pass API_TOKEN for all requests you will send to API routes.

To reduce the pain, Larakits uses custom larakits authentication guard and Larakits\Http\Middleware\CreateFreshApiToken middleware. Both will make sure that you do not need to pass any API token while accessing your API route from JavaScript Application. The authentication is automatically handled by Larakits.

If you are using axios as HTTP client, you can call your API route like a normal web route:

axios.get('/api/user')
  .then(response => {
    console.log(response)
  })

Scopes

The scopes is the way of limiting API access. User can grant the ability when creating new API token. To give user that opportunity you have to register the token’s scopes first. Your registered scopes will automatically show up on the API creating modal.

To register scopes, you may use Larakits::tokensCan method in the booted method of App\Providers\LarakitsServiceProvide:

Larakits::tokensCan([
   'create-user' => 'Create User',
   'delete-user' => 'Delete User'
]);

Checking Scopes

When a user is authenticated via API, you can perform the ability check for API token in two different ways:

Via Middleware

Route::middleware(['auth:api', 'tokenCan:create-user'])->post('/user', function () {
    //
});

Via TokenCan Method

Route::middleware(['auth:api'])->post('/user', function () {
    if(auth()->user()->tokenCan('create-user')) {
        //
    }
});