Every request to pkgplane acts as an account. A request proves which account it is with either a session, which you get by signing in on the website, or an API key, which you create once and send with each request. Sessions are for people at a browser. Keys are for everything else.
Who can have an account
pkgplane is invite-only while it’s in early access. An email address has to be on the allowlist before it can be used, and there are two ways onto it:
- An invite. An admin invites your email, and you get a link that’s good for seven days and works once. Accepting it adds your email to the allowlist and creates your account, already verified.
- Sign-up for an allowlisted email. If an admin has already allowlisted your email, you can sign up yourself. pkgplane emails you a link to verify the address before you can sign in.
The allowlist is checked on every new sign-in, not only at sign-up. Removing an email from it stops that account from signing in, by password or passkey, from then on.
Sessions and API keys
| Session | API key | |
|---|---|---|
| How you get it | Sign in with a password or passkey | Create it on the API keys page |
| How it’s sent | A cookie, set by the browser | Authorization: Bearer pkp_… |
| Lasts | Until you sign out, or it expires | Until it expires, or you disable or delete it |
| Can manage API keys | Yes | No |
| Can use admin tools | Yes, as an admin | No |
| Rate limit | Per IP address on sign-in routes | 120 requests a minute, per key |
An API key can do less than a session on purpose. If a key leaks, the person who has it can call the API as you, but they can’t create more keys to keep that access after you revoke the one they have. For the same reason, a key is never accepted where a session is required, even with admin rights.
pkgplane stores only a SHA-256 hash of each key. That’s why the full key is shown once, when you create it, and why nobody, including an admin, can look it up later.
Turning access off
Access ends as soon as pkgplane knows it should:
- Revoking a key (disable or delete) stops it on the next request.
- Signing out, resetting your password or being signed out by an admin ends sessions. A password reset ends all of them.
- A ban from an admin blocks sign-in and also blocks every API key the account has.
The API checks sessions and keys on every request, so all of this applies to API calls at once. Pages on the website may keep working for up to a minute, because the browser caches the session for that long to keep pages fast.
Admins
An admin is an account with the admin role. Admins invite people, and can search for accounts,
ban them, sign them out, send them a password reset email, change their role, act as them, and delete
them.
Some things stay out of an admin’s reach, so admin access can’t quietly become access to your account. Admins can’t set your password (you reset it yourself by email). While acting as you, an admin can’t create API keys or change your passkeys, password, email or profile.
Boundaries
Accounts belong to people. There are no organizations, teams or shared accounts yet, and API keys can’t be scoped to less than everything their owner can do. Both are coming with the package registry, because who owns a package decides how they should work.