---
title: "Handling tokens and key material safely"
description: "Handling credentials, tokens, and exported key material without creating a bad day."
---

> Documentation Index
> Fetch the complete documentation index at: https://tee.hypetrade.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling tokens and key material safely

This service holds key material. A few habits keep an integration from becoming
the weak link.

## Never commit these

- `.env.local` and any environment file carrying real values
- `config/tenants.json` — API keys and secret hashes
- Workspace directories and service state
- Tokens, workspace passwords, account passwords
- Exported key material, **including sealed blobs**

## Credentials

**Tenant credentials** (`X-Api-Key` + `X-Api-Secret`) administer every workspace
you own and mint tokens for all of them. They belong on a server you control —
never in a browser, mobile app, or anything shipped to a user.

**Workspace passwords** are unrecoverable. The service cannot reset one or
recover a workspace without it. Store them the way you store root credentials.

**Workspace tokens** are bearer credentials: whoever holds one has the scopes it
carries until it expires or is revoked. Treat a token like a password for its
whole lifetime.

## Ask for the narrowest scope

Scopes are fixed at mint time but cheap to re-mint. A service that only reads
and signs should hold `["read","sign"]`, so a leaked token cannot create or
delete anything.

`export` is never granted by default. Request it only for the specific operation
that needs it, and revoke the token immediately after.

> **Revoke when the work is done**
>
> `DELETE /v1/auth/token` revokes the lease of the token you send it with, and
> the workspace locks once its last lease goes. Ending a workflow with an
> explicit revoke shrinks the window in which that token is worth anything.
>
> Revoke the compromised token **with itself**. Revoking a different token you
> hold for the same workspace does not touch the leaked one, and refreshing does
> not either — a stolen bearer can refresh itself until the idle or absolute
> clock stops it.

## Deletion is real

Deleting a workspace or an account destroys the key material inside it. There is
no undo and no recovery from the service side.

`?force=true` on workspace deletion also revokes live sessions. Use it only when
that is what you intend — see [Manage workspaces](/guides/manage-workspaces/).

## Sealed exports are still key material

A sealed blob is your key, encrypted to a key your operator holds. That makes it
safe from a thief who lacks the private half — and nothing else. Keep it out of
logs, issue trackers, chat, and CI artifacts. Give it no longer a retention than
you would give the key itself.

Check `recipientFingerprint` before decrypting: it identifies which key the blob
was sealed to.

## Handling errors safely

- Branch on `error.code`, never on `message`.
- Do not log whole request bodies from account creation, unlock, or token mint —
  they carry passwords and secrets.
- Keep `requestId` for support. It is safe to share; the rest of the error may
  not be.

## Transactions

- Treat `status: "unknown"` and `tx_timeout` as *unestablished*, never as
  failure. Check status before resending — see
  [Send transactions](/guides/send-transactions/).
- Simulate before sending anything consequential.
- If you send from the same address by other means, manage `nonce` yourself.

## Operational hygiene

- Run one service instance per state directory. A second instance on the same
  storage is refused, deliberately, to protect wallet and quota records.
- Keep RPC endpoint credentials in operator configuration, not client code.
- Rotate tenant credentials through your operator rather than sharing them
  across environments.

## Related

- [Scopes and permissions](/concepts/scopes/)
- [Export key material](/guides/export-key-material/)
- [Errors](/errors/)

Source: https://tee.hypetrade.xyz/safe-usage/index.mdx