/ 
PAGI-FastAPI-Security-v0.0.5
/ PAGI::FastAPI::Security::HTTPBearer

NAME

PAGI::FastAPI::Security::HTTPBearer - HTTP Bearer token scheme for PAGI::FastAPI

VERSION

Version v0.0.5

SYNOPSIS

use PAGI::FastAPI::Security::HTTPBearer;

my $bearer = PAGI::FastAPI::Security::HTTPBearer->new(realm => 'my-api');

$app->get('/items',
    dependencies => [ $bearer->depends(key => 'token') ],
    handler      => async sub ($c) {
        my $token = $c->stash->{token};   # the raw bearer token string
        # ... verify $token yourself (JWT, opaque token lookup, etc.) ...
        return { items => [] };
    },
);

DESCRIPTION

Get the bearer token from the Authorization: Bearer <token> request header. This class does not verify the token, it only extracts it. You will need to combine it with your verification method (for example, Crypt::JWT for signed JWTs, or a database or cache query for opaque tokens) in your route handler, or you will need to manage verification with another Depends().

CONSTRUCTOR OPTIONS

  • realm - (Optional) Realm string sent in the WWW-Authenticate challenge header on failure. Default: 'Restricted'.

  • auto_error - (Optional) If true (this is the default value), it automatically issues a 401 Unauthorized response with a WWW-Authenticate: Bearer header and returns { detail = 'Not authenticated' }> when there is no valid bearer token available, which can completely bypass the route handler. If this is set to false, the dependency resolves as undef in case of failure, allowing optional implementation of auth.

METHODS

challenge_header

my ($key, $value) = $bearer->challenge_header;
my ($key, $value) = $bearer->challenge_header(
    error             => 'invalid_token',
    error_description => 'The access token has expired',
);

# Usage inside route checks:
$c->header($bearer->challenge_header(error => 'invalid_token'));

Overrides "challenge_header" in PAGI::FastAPI::Security::Base to generate an RFC 6750 compliant WWW-Authenticate challenge header for Bearer authentication schemes.

Returns a two-element array ('WWW-Authenticate', $challenge_string).

OPTIONS

  • error - (Optional) An ASCII error code as specified in RFC 6750 Section 3.1 (e.g., 'invalid_request', 'invalid_token', 'insufficient_scope').

  • error_description - (Optional) A human-readable text providing additional information used to assist developer troubleshooting.

EXAMPLES

Without parameters:

'WWW-Authenticate' => 'Bearer realm="Restricted"'

With error parameters:

'WWW-Authenticate' => 'Bearer realm="Restricted", error="invalid_token", error_description="The access token has expired"'

AUTHOR

Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>

REPOSITORY

https://github.com/manwar/PAGI-FastAPI-Security

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/PAGI-FastAPI-Security/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

perldoc PAGI::FastAPI::Security::HTTPBearer

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (C) 2026 Mohammad Sajid Anwar.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0