Authentication

OpenAPI has plenty of ways to describe the API authentication: https://spec.openapis.org/oas/v3.1.0#security-scheme-object.

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
    });

Excluding a route from security requirements

You can exclude a route from security requirements by adding @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
}