Documentation
¶
Overview ¶
Package apikeys issues API keys to accounts and authenticates API requests with them.
A key is the app's prefix, an underscore and 32 random bytes in base64url, such as acme_V3kz…. Only the SHA-256 of the whole key is stored, with its last characters for display. The raw key is shown once, when it is created, and never logged. Lookup is by hash, so changing the prefix never invalidates existing keys.
templ: version: v0.3.1070
Index ¶
- Variables
- type Config
- type Key
- type Keys
- func (k *Keys) Authenticate(ctx context.Context, raw string) (Key, error)
- func (k *Keys) Create(ctx context.Context, accountID, name string) (string, Key, error)
- func (k *Keys) Delete(ctx context.Context, accountID, keyID string) error
- func (k *Keys) List(ctx context.Context, accountID string) ([]Key, error)
- func (k *Keys) LockActive(ctx context.Context, tx *sql.Tx, accountID, keyID string) error
- func (k *Keys) Mount(r gin.IRouter, layout ui.Layout)
- func (k *Keys) Rename(ctx context.Context, accountID, keyID, name string) error
- func (k *Keys) RequireKey(c *gin.Context)
- func (k *Keys) Revoke(ctx context.Context, accountID, keyID string) error
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotFound means the account has no key with that ID. ErrNotFound = errors.New("apikeys: key not found") // ErrInvalidKey means a presented key is malformed, unknown or revoked. ErrInvalidKey = errors.New("apikeys: invalid key") // ErrInvalidName means a key name is empty, too long or contains control characters. ErrInvalidName = errors.New("apikeys: a key name needs 1 to 64 printable characters") // ErrActive means a key must be revoked before it can be deleted. ErrActive = errors.New("apikeys: revoke the key before deleting it") )
var Migrations = app.Migrations{Namespace: "apikeys", Files: sub(migrationFiles, "migrations")}
Migrations create the api_keys table. List them after accounts.Migrations.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Prefix starts every new key, such as "acme" for acme_… keys. Letters, digits and
// underscores, starting with a letter.
Prefix string
}
Config configures the module.
type Key ¶
type Key struct {
ID string
AccountID string
Name string
// Prefix is the module's current prefix, for display.
Prefix string
Suffix string
CreatedAt time.Time
LastUsedAt *time.Time
RevokedAt *time.Time
}
Key describes an issued key. It never holds the raw key.
type Keys ¶
type Keys struct {
// contains filtered or unexported fields
}
Keys is the API keys module.
func New ¶
New returns the API keys module. Keys belong to accounts, and a foreign key deletes them with their account.
func (*Keys) Authenticate ¶
Authenticate returns the active key matching raw. It records when the key was last used, at most every five minutes.
func (*Keys) Delete ¶
Delete removes a revoked key from the account's list. An active key returns ErrActive; a key that no longer exists counts as deleted.
func (*Keys) LockActive ¶
LockActive checks inside tx that the key still authenticates for the account, and keeps it from being revoked until tx ends. Run it in the transaction that spends credit for a request, so a key revoked meanwhile cannot spend. It returns ErrInvalidKey for a revoked or unknown key.
func (*Keys) Mount ¶
Mount adds the keys page to r, a group at the page's path that uses accounts.RequireSignIn, such as /account/api-keys:
- GET "" lists the account's keys.
- GET "/list" renders the list alone, for refreshes after a change.
- POST "" creates a key and shows it once.
- POST "/:id" renames ("action=rename" and "name"), revokes ("action=revoke") or deletes ("action=delete" and the key's name as "confirm_name") a key. Only revoked keys can be deleted.
func (*Keys) RequireKey ¶
RequireKey protects API routes. It accepts exactly one "Authorization: Bearer <key>" header, ignores cookies, and answers 401 with a JSON error otherwise. The header is removed once the key is checked, so handlers cannot log or forward it.
Source Files