/ 
Typesense-Client-0.001
/ Typesense::Client::Keys

NAME

Typesense::Client::Keys - API keys, including scoped search keys

SYNOPSIS

# A key that can only search, only this collection.
my $k = $ts->keys->create({
    description => 'storefront search',
    actions     => ['documents:search'],
    collections => ['products'],
});
my $search_key = $k->{value};    # the only time you will ever see it

# Derive a per-customer key locally - no request to the server.
my $scoped = $ts->keys->scoped($search_key, {
    filter_by => "customer_id:=$id",
    expires_at => time + 3600,
});

DESCRIPTION

Two different things live here.

Real keys are created on the server with a set of allowed actions and collections. The plaintext value is returned only in the create response - afterwards Typesense stores a hash and it cannot be recovered. If you lose it, you make a new key.

Scoped keys are derived locally by signing a set of embedded search parameters with a search-only key. They never touch the server. This is how you hand a browser a key that can only ever see its own rows: the filter is inside the signature, so it cannot be edited client-side, and expires_at makes it expire on its own.

METHODS

list

GET /keys. Metadata only, never the values.

get

GET /keys/{id}.

create

POST /keys. Body takes description, actions and collections, and optionally expires_at and value_prefix. Save value from the response.

delete

DELETE /keys/{id}. Not an error if absent.

scoped

my $key = $ts->keys->scoped($search_key, \%embedded_params);

Derives a scoped search key. Purely local: HMAC-SHA256 of the JSON parameters under $search_key, concatenated with the first four characters of that key and the payload, all base64-encoded - the scheme Typesense expects.

$search_key must be a search-only key. Signing with an admin key would hand out admin rights.

SEE ALSO

Typesense::Client

AUTHOR

SeHarrys

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by SeHarrys.

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.