Help

Keys and security

How Packlets handles your key and what you should keep in mind yourself.

Open as Markdown

The key is the only thing that tells your tool apart from all others. Whoever has it can send messages to your channel. This page explains how Packlets protects it and what you should do yourself.

The key

Formatpk_ followed by 32 letters and digits
Valid forexactly one packlet
Visibleonce, right after it's created. After that, the app only shows it masked.
Stored at Packletsonly as a SHA-256 hash. Packlets no longer knows the plain text afterwards.

The key can only be used to send: messages and the address of an app's page. It can't be used to read messages, see other packlets or change your account.

What depends on the key

The key is also the basis for the secret Packlets uses to sign two things:

Your tool needs nothing extra for this. It derives the secret itself from PACKLETS_KEY.

What you should keep in mind

  • Environment variable instead of code. Store the key in PACKLETS_KEY, not in the source code and not in the repository. An .env file belongs in .gitignore.
  • One key per tool. A separate packlet or a separate service for each tool. That way you can swap a single key without other tools going down, and you can see in the activity log which tool sent what.
  • Never in a web page. With an app, the key stays on your server. Anything in the HTML or JavaScript can be read by anyone.
  • Always verify the signature. Your webhook address is public. Don't run anything until the signature checks out.
  • Detect replays. If something must not happen twice, also check timestamp and event_id after the signature: Replay protection.
  • Input stays input. Text from the chat and from input fields comes from outside. Don't pass it unchecked to a shell, a database query or an AI with far-reaching permissions as an instruction.
  • Check the session token fully. Signature, expiry and aud, before your page shows private data.
  • Control embedding. Third-party iframes in your page with sandbox, your page itself with Content-Security-Policy: frame-ancestors 'none': Iframes and third-party content.

If a key is lost

Open the packlet's settings and create a new key. Then this happens:

  • The old key becomes invalid immediately. Calls with it get 401 invalid_key.
  • The app shows the new key once. Enter it in your tool.
  • Webhook signatures and session tokens use the new key from now on.
  • Channel, messages and settings stay as they are.

If you just forgot the key, it works the same way. The old one can't be shown again.

If you remove a service

Each service has its own key. If you remove it in the channel's settings, its key becomes invalid immediately, and its Slack, Discord and ntfy addresses stop working. Its earlier messages stay in the channel, with its name. The channel's key and the other services stay valid.

If you remove a packlet

The key becomes invalid immediately, and the channel with all its messages is deleted. This can't be undone.

Privacy

Server and database are located in the EU. You delete your account in the app, together with all packlets and messages.