NAME

Punk::APIKey - API keys for Punk applications

SYNOPSIS

package MyApp;
use Punk;
use Punk::Plugin::APIKey;

plugin 'APIKey' => {
    model  => 'ApiKey',
    owner  => 'owner_id',
    scopes => [qw(read write admin)],
};

my ($key, $row) = $c->api_key_issue(owner => $c->auth_id, label => 'CI',
                                    scopes => ['read']);

my $api = under '/api/v1' => api_key_guard(scope => 'read');

DESCRIPTION

A key is minted once, stored as a digest, presented as Authorization: Bearer, and checked by a guard that answers an API's refusals rather than a browser's. It is scoped, revocable, rate limited per key, and answerable to its owner's current standing.

This file is the distribution: it loads the compiled half and carries the version. What it holds is documented where the behaviour is.

What is here

Punk::Plugin::APIKey

The plugin, and the reference documentation: the key format, the options, the guards, the owner's standing, the per-key limit and the traps.

Punk::Model::ApiKey

The table, for an application that has not declared a model of its own.

Punk::Command::Apikey

punk apikey - issuing, listing and revoking keys from outside the browser, reading the application's own configuration rather than taking a table on the command line.

The punk_apikey Sqitch project

The schema for SQLite, PostgreSQL and MySQL, registered through Punk::Sqitch when it is installed. The DDL is in "THE SCHEMA" in Punk::Plugin::APIKey for an application that manages its schema some other way.

THE EXAMPLE

example/apikey-demo/ is the whole plugin as a running application: keys minted in a browser, spent from a terminal, narrowed by a demotion, refused by a suspension, and revoked. Generated with punk new ApiKeyDemo --sqitch sqlite, so its layout is the ordinary one.

cd example/apikey-demo
punk sqitch deploy      # two projects: this plugin's, then the app's
plackup app.psgi

Its README.md is the tour and its t/01-basic.t asserts every claim in it.

SEE ALSO

Punk::Plugin::APIKey, Punk::Auth, Punk::Sqitch.

AUTHOR

LNATION <email@lnation.org>

BUGS

Please report any bugs or feature requests to bug-punk-apikey at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Punk-APIKey.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Punk::APIKey

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)