Account by key API

Look up accounts associated with public keys

The Account by Key API allows you to find which accounts are associated with specific public keys. This is useful for discovering account ownership and authority relationships.

get_key_references

Find all accounts that have a specific public key in their owner, active, or posting authorities.

TypeScript

import { createHiveChain } from "@hiveio/wax";

const chain = await createHiveChain();

const result = await chain.api.account_by_key_api.get_key_references({
  keys: [
    "STM6vJmrwaX5TjgTS9dPH8KsArso5m91fVodJvv91j7G765wqcNM9",
    "STM5RqVBAVNp5ufMCetQtvLGLJo7unX9nyCBMMrTXRWQ9i1Zzzizh"
  ]
});

// Result is an array of arrays - one array per key
result.accounts.forEach((accountList, index) => {
  console.log(`Key ${index}: ${accountList.join(", ")}`);
});

Parameters

keys · TPublicKey[] · required

Array of public keys to look up. Keys should be in the standard Hive format (e.g., STM… or TST… for testnet).

Response

accounts · string[][]

A two-dimensional array where each element corresponds to one input key. Each sub-array contains the account names that have that key in their authorities.

The order of the outer array matches the order of keys in the request. If a key is not associated with any accounts, its corresponding array will be empty.

Example Response

{
  "accounts": [
    ["hiveio"],
    ["alice", "bob"]
  ]
}

Common use cases

Check key ownership

Verify which accounts control a specific public key:

TypeScript

const publicKey = "STM6vJmrwaX5TjgTS9dPH8KsArso5m91fVodJvv91j7G765wqcNM9";

const result = await chain.api.account_by_key_api.get_key_references({
  keys: [publicKey]
});

if (result.accounts[0].length > 0) {
  console.log(`Key is used by: ${result.accounts[0].join(", ")}`);
} else {
  console.log("Key is not associated with any accounts");
}

Bulk key lookup

Look up multiple keys efficiently in a single request:

TypeScript

const keys = [
  "STM6vJmrwaX5TjgTS9dPH8KsArso5m91fVodJvv91j7G765wqcNM9",
  "STM5RqVBAVNp5ufMCetQtvLGLJo7unX9nyCBMMrTXRWQ9i1Zzzizh",
  "STM7Qf3hVNx3xNHjVpXvRuN5KBCkcWCmqw5LbHJBkYGi5Zf8xXabc"
];

const result = await chain.api.account_by_key_api.get_key_references({
  keys
});

// Create a map of key to accounts
const keyMap = new Map();
keys.forEach((key, index) => {
  keyMap.set(key, result.accounts[index]);
});

keyMap.forEach((accounts, key) => {
  console.log(`${key}: ${accounts.length} accounts`);
});

Recover account from key

Find accounts you control when you only have the private key:

TypeScript

import { createWaxFoundation } from "@hiveio/wax";

const wax = await createWaxFoundation();

// Derive public key from private key
const privateKey = "5JkFnXrLM2ap9t3AmAxBJvQHF7xSKtnTrCTginQCkhzU5S7ecPT";
const publicKey = wax.getPublicKey(privateKey);

// Find accounts
const result = await chain.api.account_by_key_api.get_key_references({
  keys: [publicKey]
});

console.log(`You control these accounts: ${result.accounts[0].join(", ")}`);

Verify authority

Check if a key has authority for a specific account:

TypeScript

const accountName = "alice";
const keyToCheck = "STM6vJmrwaX5TjgTS9dPH8KsArso5m91fVodJvv91j7G765wqcNM9";

const result = await chain.api.account_by_key_api.get_key_references({
  keys: [keyToCheck]
});

const hasAuthority = result.accounts[0].includes(accountName);

if (hasAuthority) {
  console.log(`Key has authority for ${accountName}`);
} else {
  console.log(`Key does NOT have authority for ${accountName}`);
}

Understanding authorities

Hive accounts have three types of authorities, each with different permissions:

• Owner: Full control over the account, including authority changes
• Active: Can perform most operations like transfers and power ups
• Posting: Can post content, vote, and perform social operations

The get_key_references endpoint searches all three authority types. A key may be in one, multiple, or all authorities for an account.

To get detailed authority information for specific accounts, use the Database API’s find_accounts endpoint.