Understanding Vault Keys

This is an admin key that grants access to every operation on every server wallet. It is also used to create access tokens.

Keep the admin key securely and distribute it only between trusted team members (who you would consider admins, and need to perform administrative functions). Do not send this key to external services, only send it directly to vault (via E2E encryption), or use it in the thirdweb dashboard where it's always securely stored in your browser memory and only used to communicate with the vault through e2e encryption. Your admin keys are never revealed to anyone other than vault itself, and you.

Access Tokens are created using the admin key. Access tokens support flexible policies that allow you to restrict what it can do. It can be scoped by:

• operation type (eg signMessage or createEoa)
• operation payload (only allow specific types of transactions to be signed like restricting by chainId, toAddress, or max value)
• entity, ie, which EOAs can this access token perform operations with. Access to entities like EOAs can be scoped in 2 ways:

  • allowlist: if you have a short list (1/2) EOAs that an access token should be able to access, you can use the allowlist

  • metadata: if you have lots of entities and complex requirements for different users to access different groups of entities, you can scope by metadata. Metadata allows you to represent implicit grouping of resources and user. As an example:

    • you can create multple EOAs with metadata team: "trading-floor"
    • If you then create an access token with metadataPatterns: { key: "team", pattern: "^trading-floor$"} , this access token will only be able to access EOAs with that specific metadata parameter set.
    • This allows you to create different access tokens for different sets of EOAs, where each set is grouped together with a metadata pattern. Groups can overlap. If you want multiple groups of users with your org to have access to the same EOA, you can instead use metadata: { teams: "trading-floor, compliance" } And now use: for trading floor: metadataPatterns: { key: "teams", pattern: "trading-floor"}
      for compliance: metadataPatterns: { key: "team", pattern: "compliance"}

    This is just an example of how flexible vault’s policies can be. Patterns can be regex operators or numeric comparisons. Metadata supports arbitrary key-value as well, so you can also create other metadata fields like purpose or teamId (if you want to map it to an internal team identifier)

• An access token can be revoked instantly with your admin key.
• You can share access tokens with all members of your team. There are multiple ways you should be sharing these, depending on your team and organisation structure:
  • If you have distinct teams within your org that don't have overlapping needs to access EOAs, you can create team specific access tokens. Every member of a team within your org will get the same access token. If a member leaves and you want to remove their access, you can revoke the existing team access tokens, create a new access token with the same policies, and share the new token with remaining team members.
  • if you have a small org, where members have large overlapping needs, you can create a single access token (scoped as minimally as possible) and share it with everyone. If a member leaves, you can revoke the existing token, create a new one, and share it with your members again.
  • for the most granular permissioning, you can create a distinct access token for every member of your team with policies restricted to exactly what they need. This way the token can also be revoked individually without any side-effects to the other tokens.

The rotation code can be used to "rotate" your account. Rotating your account will:

• invalidate your old admin key, returning you a new key
• invalidate the rotation code used, returning a new rotation code
• invalidate all existing access tokens that were previously created.

The rotation code should only be stored with the "organisation owner".

It can be used in disaster scenarios when you suspect you might have leaked a key.

It can also be used when an "administrative" team member who had access to your admin key leaves your org, and you want to revoke their access.

After the rotation code is used, all exsting access tokens need to be recreated and shared with your team, and the newly received admin key must be shared with your "team admins".