Authentication

OpenAPI provides several ways to describe API authentication: https://spec.openapis.org/oas/v3.1.0#security-scheme-object.

Automatically document authentication from middleware

New in 0.13.24

Scramble can derive OpenAPI security requirements from your route middleware. Enable MiddlewareAuthSecurityStrategy in config/scramble.php:

1
'security_strategy' => \Dedoc\Scramble\SecurityDocumentation\MiddlewareAuthSecurityStrategy::class,

By default, middleware named auth or auth:* is treated as authentication middleware. When at least one documented route matches, Scramble adds a bearer security scheme to the document. Matching routes inherit it; routes without matching middleware explicitly receive security: [], which makes them public in OpenAPI.

1
Route::post('/login', [AuthController::class, 'login']);
2

3
Route::middleware('auth:sanctum')->group(function () {
4
    Route::get('/projects', [ProjectController::class, 'index']);
5
});

In this example, /projects requires bearer authentication and /login is documented as public. Protected routes also receive the automatic 401 Unauthenticated response.

Custom middleware and schemes

For custom middleware aliases or another scheme type, pass the strategy and its options:

1
'security_strategy' => [
2
    \Dedoc\Scramble\SecurityDocumentation\MiddlewareAuthSecurityStrategy::class,
3
    [
4
        'middleware' => ['api.token'],
5
        'scheme' => \Dedoc\Scramble\Support\Generator\SecurityScheme::apiKey('header', 'X-API-Key'),
6
    ],
7
],

Keep this strategy disabled if you configure document security manually, otherwise the document can contain duplicate schemes.

Excluding a route from security requirements

You can exclude a route from security requirements by adding the @unauthenticated annotation to the route method’s PHPDoc comment block.

1
/**
2
 * @unauthenticated
3
 */
4
public function index(Request $request)
5
{
6
    return response()->json(/* some data */);
7
}

Manually requiring authentication

To document API authentication, use a document transformer and add the security information to the document using secure method.

The secure method on OpenApi object accepts security scheme as an argument. It makes the security scheme default for all endpoints.

1
use Dedoc\Scramble\Scramble;
2
use Dedoc\Scramble\Support\Generator\OpenApi;
3
use Dedoc\Scramble\Support\Generator\SecurityScheme;
4

5
/**
6
 * Bootstrap any application services.
7
 *
8
 * @return void
9
 */
10
public function boot()
11
{
12
    Scramble::configure()
13
        ->withDocumentTransformers(function (OpenApi $openApi) {
14
            $openApi->secure(
15
                SecurityScheme::http('bearer')
16
            );
17
        });
18
}

Complex authentication scenario

You can also describe more complex authentication scenarios that are allowed in OpenAPI specification.

For example, imagine the API requires 2 headers for authentication: Authorization (the default bearer token header) and X-Tenant (for tenant identification). To implement such authentication:

Manually define a security scheme for these headers;
Define a security requirement that requires both headers.

1
use Dedoc\Scramble\Scramble;
2
use Dedoc\Scramble\Support\Generator\OpenApi;
3
use Dedoc\Scramble\Support\Generator\SecurityScheme;
4

5
public function boot()
6
{
7
    Scramble::configure()
8
        ->withDocumentTransformers(function (OpenApi $openApi) {
9
            $openApi->components->securitySchemes['tenant'] = SecurityScheme::apiKey('header', 'X-Tenant');
10
            $openApi->components->securitySchemes['bearer'] = SecurityScheme::http('bearer');
11

12
            $openApi->security[] = new SecurityRequirement([
13
                'tenant' => [],
14
                'bearer' => [],
15
            ]);
16
        });
17
}

Security scheme examples

Here are some common examples of security schemes objects you may have in your API. For full list of available methods check implementation of SecurityScheme class.

Bearer

One of the most common ways to add auth protection to the API is to use Authorization header with Bearer $token value. If you use this way of auth, you can document it using:

1
use Dedoc\Scramble\Support\Generator\SecurityScheme;
2

3
SecurityScheme::http('bearer');

API Key

When the API token is passed as a query parameter in URL (https://someapi.com/api/items?api_token=0000_00_0001), the next security schema can be used:

1
use Dedoc\Scramble\Support\Generator\SecurityScheme;
2

3
SecurityScheme::apiKey('query', 'api_token');

Bearer JWT

1
use Dedoc\Scramble\Support\Generator\SecurityScheme;
2

3
SecurityScheme::http('bearer', 'JWT');

Basic HTTP

1
use Dedoc\Scramble\Support\Generator\SecurityScheme;
2

3
SecurityScheme::http('basic');

Oauth2

1
use Dedoc\Scramble\Support\Generator\SecurityScheme;
2
use Dedoc\Scramble\Support\Generator\SecuritySchemes\OAuthFlow;
3

4
SecurityScheme::oauth2()
5
    ->flow('authorizationCode', function (OAuthFlow $flow) {
6
        $flow
7
            ->authorizationUrl(config('app.url').'/oauth/authorize')
8
            ->tokenUrl(config('app.url').'/oauth/token')
9
            ->addScope('*', 'all');
10
    });