{"id":30692251,"url":"https://github.com/stfsy/go-api-key","last_synced_at":"2025-09-02T04:50:39.139Z","repository":{"id":311114557,"uuid":"1042517353","full_name":"stfsy/go-api-key","owner":"stfsy","description":"Simple, extensible API key generator for Go, supporting custom random ID generators and token hashers.","archived":false,"fork":false,"pushed_at":"2025-08-22T06:34:09.000Z","size":9,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-22T08:41:34.836Z","etag":null,"topics":["api","authentication","go"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stfsy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-22T06:27:23.000Z","updated_at":"2025-08-22T06:31:24.000Z","dependencies_parsed_at":"2025-08-22T08:41:36.978Z","dependency_job_id":null,"html_url":"https://github.com/stfsy/go-api-key","commit_stats":null,"previous_names":["stfsy/go-api-key"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/stfsy/go-api-key","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stfsy%2Fgo-api-key","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stfsy%2Fgo-api-key/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stfsy%2Fgo-api-key/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stfsy%2Fgo-api-key/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stfsy","download_url":"https://codeload.github.com/stfsy/go-api-key/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stfsy%2Fgo-api-key/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273233264,"owners_count":25068731,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","authentication","go"],"created_at":"2025-09-02T04:50:35.675Z","updated_at":"2025-09-02T04:50:39.109Z","avatar_url":"https://github.com/stfsy.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-api-key\n\nThis package provides a simple, extensible API key generator for Go, supporting custom random ID generators and token hashers.\n\n## Features\n- Generate API keys with a customizable prefix, short token, and long token.\n- Use your own random ID generator and token hasher, or use the secure defaults.\n- Parse and validate API keys.\n\n## Installation\n\n```sh\ngo get github.com/stfsy/go-api-key\n```\n\n## Example\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"github.com/stfsy/go-api-key\"\n)\n\nfunc main() {\n\t// Create a generator with default secure random and Argon2id hasher\n\tgen, err := apikey.NewApiKeyGenerator(apikey.ApiKeyGeneratorOptions{\n\t\tTokenPrefix: \"mycorp\",\n\t\t// Optionally:\n\t\t// TokenIdGenerator:    \u0026apikey.DefaultRandomBytesGenerator{},\n\t\t// TokenBytesGenerator: \u0026apikey.DefaultRandomBytesGenerator{},\n\t\t// TokenHasher:         \u0026apikey.Sha256Hasher{}, // or \u0026apikey.Argon2IdHasher{}\n\t})\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\t// Generate a new API key\n\tkey, err := gen.GenerateAPIKey()\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(\"API Key:\", key.Token)\n\n\t// Parse and check\n\tparsed, err := gen.GetTokenComponents(key.Token)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Printf(\"Short: %s, Long: %s, Hash: %s\\n\", parsed.ShortToken, parsed.LongToken, parsed.LongTokenHash)\n\n\tok, err := gen.CheckAPIKey(key.Token, key.LongTokenHash)\n\tfmt.Println(\"Valid:\", ok, \"Error:\", err)\n}\n```\n\n## Notes\n\n- The token prefix must be 1-8 characters, using only `[a-zA-Z0-9_-]` and must not contain the separator (`#`).\n- The default separator is `#`.\n- You can provide your own implementations of `RandomBytesGenerator` and `Hasher` for custom behavior/testing.\n\n## API Overview\n\n### Constructors\n\n#### `NewApiKeyGenerator`\n\n```go\nfunc NewApiKeyGenerator(opts ApiKeyGeneratorOptions) (*APIKeyGenerator, error)\n```\n\nCreate a new API key generator. All options are set via the `ApiKeyGeneratorOptions` struct:\n\n```go\ntype ApiKeyGeneratorOptions struct {\n\tTokenPrefix         string // required, 1-8 chars, [a-zA-Z0-9_-], no separator\n\tTokenSeparator      rune   // optional, defaults to '#'\n\tTokenIdGenerator    RandomBytesGenerator // optional, defaults to secure random\n\tTokenBytesGenerator RandomBytesGenerator // optional, defaults to secure random\n\tTokenHasher         Hasher               // optional, defaults to SHA256\n\tShortTokenBytes     int                  // optional, defaults to 8\n\tLongTokenBytes      int                  // optional, defaults to 64\n}\n```\n\n### Interfaces\n\n\n#### `RandomBytesGenerator`\n\n```go\ntype RandomBytesGenerator interface {\n\tGenerate(n int) (string, error)\n}\n```\nDefault: `DefaultRandomBytesGenerator` (crypto/rand, base64 URL encoding)\n\n#### `Hasher`\n\n```go\ntype Hasher interface {\n\tHash(token string) (string, error)\n\tVerify(token, hash string) bool\n}\n```\nDefault: `Argon2IdHasher` (Argon2id hash string). You can also use `Sha256Hasher` (SHA256 hex string).\n\n### Methods\n\n#### `(*APIKeyGenerator) GenerateAPIKey()`\n\nGenerate a new API key:\n\n```go\nkey, err := gen.GenerateAPIKey()\n// key.ShortToken, key.LongToken, key.LongTokenHash, key.Token\n```\n\n#### `(*APIKeyGenerator) ExtractShortToken(token string) (string, error)`\n#### `(*APIKeyGenerator) ExtractLongToken(token string) (string, error)`\n#### `(*APIKeyGenerator) GetTokenComponents(token string) (*APIKey, error)`\n#### `(*APIKeyGenerator) CheckAPIKey(token, hash string) (bool, error)`\n\n#### Hashing and Verifying tokens directly\n\nYou can use a hasher directly:\n\n```go\nhasher := \u0026apikey.Argon2IdHasher{}\nhash, err := hasher.Hash(\"sometoken\")\nif err != nil {\n\tpanic(err)\n}\nok := hasher.Verify(\"sometoken\", hash)\n```\n\n## Related Work\n- [seamapi/prefixed-api-key](https://github.com/seamapi/prefixed-api-key/tree/main) – inspiration and reference for prefixed API key design.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstfsy%2Fgo-api-key","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstfsy%2Fgo-api-key","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstfsy%2Fgo-api-key/lists"}