Skip to main content

Getting Started

Obtaining an API Key​

API keys are issued by the Emerald admin team. Contact your account manager or request one through the admin dashboard. Each key is scoped to a single partner organization.

Once you have your key, it will look like this:

sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Base URL​

EnvironmentURL
Productionhttps://api.emeraldvaults.io
Developmenthttp://localhost:3001

Authentication​

Include your API key in the x-api-key header on all partner requests:

curl -H "x-api-key: sk-your-api-key-here" \
  https://api.emeraldvaults.io/api/v1/partner/vaults

Public endpoints (under /api/v1/vaults, /api/v1/users, etc.) require no authentication.

Rate Limits​

ParameterValue
Default limit100 requests per minute per API key
Maximum configurable10,000 requests per minute
WindowSliding 1-minute window
Exceeded responseHTTP 429 with error code RATE_LIMITED

When you receive a 429 response, implement exponential backoff:

async function fetchWithRetry(url: string, apiKey: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, {
      headers: { "x-api-key": apiKey },
    });

    if (res.status === 429) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise((r) => setTimeout(r, delay));
      continue;
    }

    return res.json();
  }

  throw new Error("Rate limit exceeded after retries");
}

Next Steps​