feat(format): rename default prefix from to for versioned key format

Author: Athroniaeth

README.md

@@ -44,6 +44,10 @@ This library try to follow best practices and relevant RFCs for API key manageme
   pattern (`^[a-z][a-z0-9:_\-]*$`) at the schema level. Note: [RFC 6749 §3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)
   permits a broader character set; this restriction is a deliberate keyshield design choice to
   prevent injection of arbitrary characters (HTML, SQL fragments, etc.) in scope values.
+- **Versioned key format** (industry best practice, aligned with Stripe/GitHub 2023+): the default
+  prefix embeds a format version (`ak_v1`, `ak_v2`, …) so a future algorithm or structure migration
+  can be detected at parse time — old keys keep their prefix and old keys always fail with `401`
+  rather than silently producing wrong hashes.  Custom prefixes are still fully supported.
 
 ## Installation
 
@@ -158,10 +162,10 @@ This is a classic API key if you don't modify the service behavior:
 
 **Example:**
 
-`ak-7a74caa323a5410d-mAfP3l6yAxqFz0FV2LOhu2tPCqL66lQnj3Ubd08w9RyE4rV4skUcpiUVIfsKEbzw`
+`ak_v1-7a74caa323a5410d-mAfP3l6yAxqFz0FV2LOhu2tPCqL66lQnj3Ubd08w9RyE4rV4skUcpiUVIfsKEbzw`
 
 - "-" separators so that systems can easily split
-- Prefix `ak` (for "Api Key"), to identify the key type (useful to indicate that it is an API key).
+- Prefix `ak_v1` (for "Api Key v1"), to identify both the key type and the format version — allowing future algorithm migrations without breaking existing keys (e.g. `ak_v2-…` for a future format).
 - 16 first characters are the identifier (UUIDv4 without dashes)
 - 64 last characters are the secret (random alphanumeric string)
 
@@ -189,7 +193,7 @@ flowchart LR
 
     %% ── Entry ───────────────────────────────────────────────
     INPUT(["`**Api Key**
-    _ak-7a74…10d-mAfP…bzw_`"]):::startNode
+    _ak_v1-7a74…10d-mAfP…bzw_`"]):::startNode
 
     %% ── Main flow ───────────────────────────────────────────
     CACHED{"`**Is cached key?**
@@ -256,7 +260,7 @@ flowchart LR
     {separator}: str
     {key_secret}: UUID
 
-    _global_prefix = 'ak'_
+    _global_prefix = 'ak_v1'_
     _separator = '-'_`"]:::noteStyle
 
     NOTE_CACHE["`**Cache rules**

docs/index.md

@@ -40,6 +40,10 @@ This library try to follow best practices and relevant RFCs for API key manageme
 - **[NIST SP 800-132](https://csrc.nist.gov/publications/detail/sp/800-132/final)**: The Bcrypt hasher
   pre-hashes the secret via `HMAC-SHA256(pepper, secret)` before passing it to bcrypt, producing a fixed
   32-byte digest that eliminates bcrypt's silent 72-byte input truncation.
+- **Versioned key format** (industry best practice, aligned with Stripe/GitHub 2023+): the default
+  prefix embeds a format version (`ak_v1`, `ak_v2`, …) so a future algorithm or structure migration
+  can be detected at parse time — old keys keep their prefix and always fail with `401`
+  rather than silently producing wrong hashes.  Custom prefixes are still fully supported.
 
 ## How API Keys Work
 
@@ -53,10 +57,10 @@ This is a classic API key if you don't modify the service behavior:
 
 **Example:**
 
-`ak-7a74caa323a5410d-mAfP3l6yAxqFz0FV2LOhu2tPCqL66lQnj3Ubd08w9RyE4rV4skUcpiUVIfsKEbzw`
+`ak_v1-7a74caa323a5410d-mAfP3l6yAxqFz0FV2LOhu2tPCqL66lQnj3Ubd08w9RyE4rV4skUcpiUVIfsKEbzw`
 
 - "-" separators so that systems can easily split
-- Prefix `ak` (for "Api Key"), to identify the key type (useful to indicate that it is an API key).
+- Prefix `ak_v1` (for "Api Key v1"), to identify both the key type and the format version — allowing future algorithm migrations without breaking existing keys (e.g. `ak_v2-…` for a future format).
 - 16 first characters are the identifier (UUIDv4 without dashes)
 - 64 last characters are the secret (random alphanumeric string)
 
@@ -84,7 +88,7 @@ flowchart LR
 
     %% ── Entry ───────────────────────────────────────────────
     INPUT(["`**Api Key**
-    _ak-7a74…10d-mAfP…bzw_`"]):::startNode
+    _ak_v1-7a74…10d-mAfP…bzw_`"]):::startNode
 
     %% ── Main flow ───────────────────────────────────────────
     CACHED{"`**Is cached key?**
@@ -151,7 +155,7 @@ flowchart LR
     {separator}: str
     {key_secret}: UUID
 
-    _global_prefix = 'ak'_
+    _global_prefix = 'ak_v1'_
     _separator = '-'_`"]:::noteStyle
 
     NOTE_CACHE["`**Cache rules**

docs/usage/django.md

@@ -125,7 +125,7 @@ async def get_service() -> CachedApiKeyService:
 
 ```python
 import os
-os.environ["API_KEY_DEV"] = "ak-mydevkeyid-mysecret64chars"
+os.environ["API_KEY_DEV"] = "ak_v1-mydevkeyid-mysecret64chars"
 
 async def get_service() -> ApiKeyService:
     svc = ApiKeyService(repo=DjangoApiKeyRepository(), hasher=Argon2ApiKeyHasher())

docs/usage/dotenv.md

@@ -5,7 +5,7 @@ If you don't need to have complex system (add, remove, update API keys) manageme
 You can generate API keys using the CLI `create` command or programmatically, then store them in your `.env` file:
 
 ```bash
-API_KEY_DEV=ak-dcde9fa8eec44aa2-n8JK2HPXoosH6UXPL5h2YeO3OdW55WESb97CKc7mbVUzFpWFQYLuDD7Xs8fbco5d
+API_KEY_DEV=ak_v1-dcde9fa8eec44aa2-n8JK2HPXoosH6UXPL5h2YeO3OdW55WESb97CKc7mbVUzFpWFQYLuDD7Xs8fbco5d
 ```
 
 ## Example

docs/usage/litestar.md

@@ -125,7 +125,7 @@ async def provide_svc() -> CachedApiKeyService:
 
 ```python
 import os
-os.environ["API_KEY_DEV"] = "ak-mydevkeyid-mysecret64chars"
+os.environ["API_KEY_DEV"] = "ak_v1-mydevkeyid-mysecret64chars"
 
 async def provide_svc() -> ApiKeyService:
     svc = ApiKeyService(repo=InMemoryApiKeyRepository(), hasher=Argon2ApiKeyHasher())

docs/usage/quart.md

@@ -109,7 +109,7 @@ async def get_service() -> CachedApiKeyService:
 
 ```python
 import os
-os.environ["API_KEY_DEV"] = "ak-mydevkeyid-mysecret64chars"
+os.environ["API_KEY_DEV"] = "ak_v1-mydevkeyid-mysecret64chars"
 
 async def get_service() -> ApiKeyService:
     svc = ApiKeyService(repo=InMemoryApiKeyRepository(), hasher=Argon2ApiKeyHasher())

examples/example_inmemory_env.py

@@ -22,7 +22,7 @@
 # load_dotenv()
 
 # Ensure that you respect the format of service
-os.environ["API_KEY_DEV"] = "ak-92f5326fb9b44ab7-fSvBMig0r2vY3WR2SmGoZwM949loPU7Yy1JkjIz3RzfCEkQrprQWqQuToLbM2FzN"
+os.environ["API_KEY_DEV"] = "ak_v1-92f5326fb9b44ab7-fSvBMig0r2vY3WR2SmGoZwM949loPU7Yy1JkjIz3RzfCEkQrprQWqQuToLbM2FzN"
 
 
 async def main():

src/keyshield/_schemas.py

@@ -125,7 +125,9 @@ class ApiKeySearchIn(BaseModel):
     last_used_after: Optional[datetime] = Field(None, description="Keys last used after this date")
     never_used: Optional[bool] = Field(None, description="True = never used keys, False = used keys")
     scopes_contain_all: Optional[List[_ScopeStr]] = Field(None, description="Keys must have ALL these scopes")
-    scopes_contain_any: Optional[List[_ScopeStr]] = Field(None, description="Keys must have at least ONE of these scopes")
+    scopes_contain_any: Optional[List[_ScopeStr]] = Field(
+        None, description="Keys must have at least ONE of these scopes"
+    )
     name_contains: Optional[str] = Field(None, description="Name contains this substring (case-insensitive)")
     name_exact: Optional[str] = Field(None, description="Exact name match")
     order_by: SortableColumn = Field(SortableColumn.CREATED_AT, description="Field to sort by")

src/keyshield/services/base.py

@@ -18,15 +18,15 @@
 Default separator between key_type, key_id, key_secret in the API key string.
 Must be not in `token_urlsafe` alphabet. (like '.', ':', '~", '|')
 """
-DEFAULT_GLOBAL_PREFIX = "ak"
+DEFAULT_GLOBAL_PREFIX = "ak_v1"
 
 
 @dataclass
 class ParsedApiKey:
     """Result of parsing an API key string.
 
     Attributes:
-        global_prefix: The prefix identifying the key type (e.g., "ak").
+        global_prefix: The prefix identifying the key type (e.g., "ak_v1").
         key_id: The public identifier part of the API key.
         key_secret: The secret part of the API key.
         raw: The original full API key string.
@@ -45,7 +45,7 @@ class AbstractApiKeyService(ABC):
         repo: Repository for persisting API key entities.
         hasher: Hasher for hashing secrets. Defaults to Argon2ApiKeyHasher.
         separator: Separator in API key format. Defaults to "-".
-        global_prefix: Prefix for API keys. Defaults to "ak".
+        global_prefix: Prefix for API keys. Defaults to "ak_v1".
         rrd: Deprecated random response delay. Ignored if provided.
         min_delay: Minimum delay (seconds) applied to all verify responses.
         max_delay: Maximum delay (seconds) applied to all verify responses.

src/keyshield/services/cached.py

@@ -13,7 +13,7 @@
 from keyshield.domain.entities import ApiKey
 from keyshield.hasher.base import ApiKeyHasher
 from keyshield.repositories.base import AbstractApiKeyRepository
-from keyshield.services.base import DEFAULT_SEPARATOR
+from keyshield.services.base import DEFAULT_SEPARATOR, DEFAULT_GLOBAL_PREFIX
 
 INDEX_PREFIX = "idx"
 """Prefix for the secondary index mapping key_id to cache_key."""
@@ -56,7 +56,7 @@ def __init__(
         cache_prefix: str = "api_key",
         cache_ttl: int = 300,
         separator: str = DEFAULT_SEPARATOR,
-        global_prefix: str = "ak",
+        global_prefix: str = DEFAULT_GLOBAL_PREFIX,
         rrd: Optional[float] = None,
         min_delay: float = 0.1,
         max_delay: float = 0.3,