PHPackages                             kynx/api-key-generator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. kynx/api-key-generator

ActiveLibrary[Authentication & Authorization](/categories/authentication)

kynx/api-key-generator
======================

Generate and parse well-formed API keys

2.3.1(6mo ago)23.7k↑313.3%[2 issues](https://github.com/kynx/api-key-generator/issues)1BSD-3-ClausePHPPHP ~8.3.0 || ~8.4.0 || ~8.5.0CI passing

Since Jul 21Pushed 3w ago1 watchersCompare

[ Source](https://github.com/kynx/api-key-generator)[ Packagist](https://packagist.org/packages/kynx/api-key-generator)[ RSS](/packages/kynx-api-key-generator/feed)WikiDiscussions 2.3.x Synced yesterday

READMEChangelog (8)Dependencies (5)Versions (16)Used By (1)

kynx/api-key-generator
======================

[](#kynxapi-key-generator)

[![Build Status](https://github.com/kynx/api-key-generator/workflows/Continuous%20Integration/badge.svg)](https://github.com/kynx/api-key-generator/actions?query=workflow%3A%22Continuous+Integration%22)

Generate and parse well-formed API keys.

Introduction
------------

[](#introduction)

API keys are a common way to authenticate users accessing an API. While there isn't a standard saying how they should be constructed, there are some best practices.

An API key should:

- Be secure (OK, that's a little obvious...)
- Not leak any details about the user identity it is tied to
- Be easy to store securely and validate against a persistence layer
- Be traceable in case some idiot checks one into VCS - for instance, using [GitHub's Secret Scanning](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning)
- Provide a way to quickly reject obviously malformed keys without hitting the persistence layer
- Contain human-readable information so end users / support can easily see if they are using the right key
- Be easy to copy-and-paste from a UI into the consuming application

This library helps with this, providing an `ApiKeyGenerator` for generating and parsing keys, and an `ApiKey` object for working with the keys themselves. It does not provide help with storing and verifying the keys - tha part is up to you.

Installation
------------

[](#installation)

```
composer require kynx/api-key-generator

```

Usage
-----

[](#usage)

### Generating a key

[](#generating-a-key)

```
use Kynx\ApiKey\KeyGenerator;

require 'vendor/autoload.php';

$generator = new KeyGenerator('xyz_sandbox');
$apiKey    = $generator->generate();
echo $apiKey->getKey() . "\n";
```

This will output something like:

```
xyz_sandbox_miWh6l3ftyzi9TRmpZeJ4nU3LpBF5T37FguT1p4y_dab13e9d

```

See the [examples](./examples) directory for code showing how to modify the key strength, change the characters used, etc.

### Parsing a key

[](#parsing-a-key)

```
use Kynx\ApiKey\KeyGenerator;

require 'vendor/autoload.php';

$generator = new KeyGenerator('xyz_sandbox');
$apiKey    = $generator->parse('xyz_sandbox_miWh6l3ftyzi9TRmpZeJ4nU3LpBF5T37FguT1p4y_dab13e9d');
if ($apiKey === null) {
    echo "Invalid key!\n";
} else {
    echo "Identifier : " . $apiKey->getIdentifier() . "\n";
    echo "Secret     : " . $apiKey->getSecret() . "\n";
}
```

Since the key is well-formed, this will output:

```
Identifier : miWh6l3f
Secret     : tyzi9TRmpZeJ4nU3LpBF5T37FguT1p4y

```

Now make a random change to the key. The `parse()` method will return `null` and you will see the`Invalid key!`message.

**Note:** Just because a key is well-formed does **not** mean the user can be authenticated. It just means it looks like it was generated by you. You **must** still verify the key against your persistent storage.

### Handling old keys

[](#handling-old-keys)

What happens if you change the prefix for your key, or want to increase the secret strength (see [below](#secret))? You will want to issue all new keys with the updated settings, but will still need to parse old keys.

This is what the `KeyGeneratorChain` is for:

```
use Kynx\ApiKey\KeyGenerator;
use Kynx\ApiKey\KeyGeneratorChain;

require '../vendor/autoload.php';

$newPrefix = 'abc_sandbox';
$oldPrefix = 'xyz_sandbox';

$primary  = new KeyGenerator($newPrefix);
$fallback = new KeyGenerator($oldPrefix);
$chain    = new KeyGeneratorChain($primary, $fallback);

$oldKey = $chain->parse('xyz_sandbox_miWh6l3ftyzi9TRmpZeJ4nU3LpBF5T37FguT1p4y_dab13e9d');
if ($oldKey !== null) {
    echo "Old key parsed\n";
}

$newKey = $chain->parse('abc_sandbox_miWh6l3ftyzi9TRmpZeJ4nU3LpBF5T37FguT1p4y_dab13e9d');
if ($newKey !== null) {
    echo "New key parsed\n";
}
```

New keys will always be generated by the `$primary` KeyGenerator. When parsing, the `$primary` will be tried first. If it returns null, each of the `$fallback` KeyGenerators will be tried in turn, with the first successful parse result returned, or `null` if none match. See [parse-chain](./examples/parse-chain.php) for a more complete example.

API Key Structure
-----------------

[](#api-key-structure)

You will notice in the examples above that the generated key is composed of three parts separated by underscores. They are:

```
__

```

### Prefix

[](#prefix)

The `prefix` is always what you passed as the first argument passed to the KeyGenerator constructor. It is there to make your key easy to recognise, both to end users and to secret scanners that find leaked keys in the wild. In the examples we've used a company identifier (`xyz`) plus a string indicating whether it's for use in our `production` or `sandbox`environments. If you've ever integrated with Stripe you will be familiar with this pattern, but you are free to use whatever format makes sense.

### Identifier

[](#identifier)

The `identifier` is a random string that can be used to look up the secret in a database. Store this un-hashed in a case-sensitive column (for example, `VARBINARY` in MySQL) and put a unique constraint on it. The generated identifiers are *not* guaranteed to be unique, so when inserting into the database your should be prepared to catch the constraint violation, generate a new key and re-try. See [store-and-authenticate](./examples/store-and-authenticate.php) for an example.

### Secret

[](#secret)

The `secret` part provides the security. This **must** be hashed (using PHP's [password\_hash()](https://www.php.net/password_hash)) before storing. See the [store-and-authenticate](./examples/store-and-authenticate.php) example code if you are unsure how to do this.

### Checksum

[](#checksum)

Finally the `checksum` is a `crc32b` hash of the rest of the key. It is there to quickly filter out garbage hitting your API, without needing to bother your persistence layer. Just because it matches does **not** mean the user can be authenticated! You still need to check the identifier and secret against what you stored when the key was generated.

### Defaults

[](#defaults)

By default the `identifier` is 8 characters long. With the default characters this gives `pow(59, 8) - 1` combinations. Even with millions of keys in storage the risk of collisions is tiny. Given that API keys are only really suitable for organisation-level access control, this should be plenty. But if needed you can increase it.

By default the `secret` is 32 characters long. You can improve the security of your API by increasing this. See the [generate-secure](./examples/generate-secure.php) example.

By default the generated part of the key is composed of the characters `[a-zA-Z0-9_]`. You should ensure your `prefix`is too: this makes it easy to copy it from your key management console. Try double-clicking on `xyz-sandbox_Pu!Lo&jP_N22/Oh5hz48h4.QM_e07f9ca3` to see what happens when other characters are present. If you want more entropy, make your secret longer.

Upgrading
---------

[](#upgrading)

1.x -> 2.x
-------------

[](#1x---2x)

In 1.x the default secret key length was 16 characters. Much as I hate BC breaks, this was too low for a library advocating best practice. In 2.x the default is 32 and the minimum is 24. I think it is better to fix this mistake early.

To upgrade without breaking existing keys you will need to use the `KeyGeneratorChain` along with a BC generator for parsing the old keys:

```
use Kynx\ApiKey\BcKeyGenerator;
use Kynx\ApiKey\KeyGenerator;
use Kynx\ApiKey\KeyGeneratorChain;

require 'vendor/autoload.php';

$primary  = new KeyGenerator('xyz_sandbox');
$fallback = new BcKeyGenerator('xyz_sandbox');
$chain    = new KeyGeneratorChain($primary, $fallback);

$newKey = $chain->generate(); // get a new 2.x key
$oldKey = $chain->parse('xyz_sandbox_PudLoQjP_N227Oh5hz48h4FQM_e07f9ca3'); // 1.x key still parsed
```

The `BcKeyGenerator` cannot be used for generating new keys, only for parsing old ones. It and the associated `BcApiKey`are deprecated will be dropped in version 3.x.

Further reading
---------------

[](#further-reading)

-  Original inspiriation for this package. Includes additional useful information on managing and rotating keys.
-  Covers much of the same ground, but the checklist at the end is useful for evaluating and API key security. People will be evaluating yours!
- [https://cheatsheetseries.owasp.org/cheatsheets/Key\_Management\_Cheat\_Sheet.html](https://cheatsheetseries.owasp.org/cheatsheets/Key_Management_Cheat_Sheet.html) OWASP Key Management cheat sheet.

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance62

Regular maintenance activity

Popularity25

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity69

Established project with proven stability

 Bus Factor1

Top contributor holds 75% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~89 days

Recently: every ~127 days

Total

13

Last Release

11d ago

Major Versions

1.1.x-dev → 2.0.02023-07-23

PHP version history (5 changes)1.0.0PHP ~8.2

2.0.x-devPHP ~8.2.0 || ~8.3.0

2.2.0PHP ~8.2.0 || ~8.3.0 || ~8.4.0

2.3.0PHP ~8.3.0 || ~8.4.0

2.3.1PHP ~8.3.0 || ~8.4.0 || ~8.5.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/a11d32344c8f2811ccd9930cbf5c9191039e2f063f547dcbcc1bb9ec30843376?d=identicon)[kynx](/maintainers/kynx)

---

Top Contributors

[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (45 commits)")[![kynx](https://avatars.githubusercontent.com/u/1320145?v=4)](https://github.com/kynx "kynx (15 commits)")

---

Tags

apisecurityAuthentication

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/kynx-api-key-generator/health.svg)

```
[![Health](https://phpackages.com/badges/kynx-api-key-generator/health.svg)](https://phpackages.com/packages/kynx-api-key-generator)
```

###  Alternatives

[league/oauth2-server

A lightweight and powerful OAuth 2.0 authorization and resource server library with support for all the core specification grants. This library will allow you to secure your API with OAuth and allow your applications users to approve apps that want to access their data from your API.

6.7k147.0M290](/packages/league-oauth2-server)[scheb/2fa

Two-factor authentication for Symfony applications (please use scheb/2fa-bundle to install)

585684.2k1](/packages/scheb-2fa)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)