Documenting multitenant API in Laravel with Scramble

February 21, 2025

Learn how to get document multitenant APIs with Scramble.

With Scramble, you can document tenant-aware APIs with ease. In this blog post, I’ll review common ways of identifying a tenant in multitenant APIs and how to document such APIs.

Subdomain

You may implement a multitenant API using subdomains like so: https://{tenant}.todo.app. With this implementation, tenants will have their APIs available on subdomains. For example, the dedoc tenant will have this domain: https://dedoc.todo.app.

In this case, API documentation needs to provide a way to specify this subdomain for trying things out.

Here is how you can register routes with subdomains (in routes/api.php):

Route::domain('{tenant}.todo.app')->group(function () {
    Route::apiResource('job', JobController::class)->only(['store']);
});

The OpenAPI specification has a useful concept for this called server variables. Using these variables, it is possible to describe subdomains.

In this case, we’ll have tenant server variable.

When documenting multitenant APIs, first you’d need to publish the config:

php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider" --tag="scramble-config"

Now, add a server configuration with your subdomain:

+   'servers' => [
+       'Live' => 'https://{tenant}.todo.app/api',
+   ],

Scramble will automatically document server variables, but you also can document default value and description:

public function boot(): void
{
    Scramble::configure()
        ->withServerVariables([
            'tenant' => new ServerVariable(
                default: 'demo',
                description: 'The tenant name.'
            )
        ]);
}

Depending on the currently authenticated tenant, we may also overwrite the default value of the server variable. This way, authenticated users will see their tenant name in the domain name in the API documentation.

public function boot(): void
{
    Scramble::configure()
        ->withServerVariables([
            'tenant' => ServerVariable::make(
                default: 'demo',
                description: 'The tenant name.'
            )
        ])
        ->withDocumentTransformers(function (OpenApi $document) {
                $document->servers[0]->variables['tenant']->default = /* the logic of retrieving the current tenant */;
            });
}

Consumers of this API documentation will be able to set a tenant value and try it out.

Header or query parameters

If you don’t use tenant-specific domain names, you can use different parameters in HTTP requests to identify the tenant. For example:

• A custom HTTP header, such as X-Tenant-ID
• A query string, such as https://todo.app/api?tenant=dedoc

To add such parameters to the endpoint documentation, you can use operation transformers:

public function boot(): void
{
    Scramble::configure()
        ->withOperationTransformers(function (Operation $operation) {
            $operation->parameters[] = (new Parameter(name: 'X-Tenant-ID', in: 'header'))
                ->description('The tenant ID')
                ->setSchema(Schema::fromType(new StringType));
        });
}

Conclusion

The OpenAPI specification allows you to document server variables that come from subdomain routing. Using Scramble, you can document tenant-aware APIs that use subdomains for tenant identification, as well as HTTP parameters used to identify the tenant.

Give Scramble a try if you haven’t yet: https://scramble.dedoc.co/