# Environment Setup — API Keys & Client Install

> How to install a client, store your ImageToTable.ai API key safely, and troubleshoot the most common "I sent a request and got an error" problems before you start calling the v1 API.

This page is for anyone who hasn't called an HTTP API from a terminal before. If you're already comfortable with `curl` and environment variables, skip straight to [Quickstart](/developers/quickstart).

## Install a client

You need something that can send an HTTP request with custom headers. Two common options:

- **curl** — a command-line tool, usually already installed on macOS and Linux. Check with `curl --version` in a terminal. On Windows, install it via [curl.se/windows](https://curl.se/windows/) or use curl bundled with Git Bash / WSL. Every example in these docs is written as a curl command first.
- **Postman** (or Insomnia) — a graphical app for building and saving requests, useful if you'd rather click through a form than write shell commands. Install it from [postman.com/downloads](https://www.postman.com/downloads/), then recreate any curl example on this site by copying the URL, method, headers, and body into a new request.

## Using the Python examples

Every code sample on this site has a Python tab built on the popular [`requests`](https://requests.readthedocs.io/) library — **not an official ImageToTable.ai SDK** (we don't publish one; these are plain HTTP calls with any standard client). You need:

- **Python 3.8+** — check with `python3 --version`. Get it from [python.org/downloads](https://www.python.org/downloads/) if it's missing.
- **`requests`** — not part of the standard library, install it first:`pip install requests`(or `pip3 install requests`, depending on your system).

The export examples that parse the downloaded file (xlsx/docx) also use `openpyxl` / `python-docx` — only needed if you're following those specific examples, install with `pip install openpyxl python-docx`.

## Using the JavaScript examples

The JavaScript tab uses the native `fetch` API — no library to install — but does assume a reasonably current runtime:

- **Node.js 20+** if running server-side — check with `node --version`. Examples use top-level `await` and the global `crypto.randomUUID()`, both of which need a recent Node; on Node 18 (now end-of-life) `crypto` isn't reliably a global outside CommonJS/REPL and these examples can fail with a confusing `crypto is not defined` error that has nothing to do with your API key. Get a current version from [nodejs.org](https://nodejs.org/).
- Or just **paste the snippet into a browser's DevTools console** — every modern browser supports the same APIs (`fetch`, `FormData`, `crypto.randomUUID()`) natively, no install needed at all.

## Get your API key

Your API key is issued from your account's [profile settings page](/profile/). The v1 API is available to paid plans (Basic and above); calling it from a Free-plan key returns a `plan_required` error rather than a missing-auth error, since the key itself is valid — it just isn't allowed to use v1 yet.

## Store your key as an environment variable

Don't paste your key directly into a command you might share, screenshot, or commit to version control. Export it into your shell session instead, then reference it as `$API_KEY` in every request — every example on this site assumes this variable exists:

```bash
export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

This only lasts for your current terminal session. For something more permanent, add the same line to your shell's startup file (`~/.bashrc`, `~/.zshrc`, or equivalent) — or, if you're writing a script, load it from a `.env` file / secrets manager rather than hardcoding it in source.

## Send a test request

Confirm your key and setup work before moving on to real documents:

```bash
curl https://imagetotable.ai/api/v1/account \
  -H "Authorization: Bearer $API_KEY"
```

A working key on a paid plan returns your account snapshot (plan, role, available credits). Anything else, see the troubleshooting checklist below.

## Troubleshooting checklist

Every v1 error comes back as JSON with a `type`/`code`/`message` — see the full [Error Handling](/developers/guides/errors) guide for the complete list. The fastest first checks for a request that isn't working:

- **Getting `missing_api_key`?** Check the header is exactly `Authorization: Bearer <key>` — the word `Bearer`, a single space, then the key. A missing space or a stray quote character in `$API_KEY` both produce this.
- **Getting `invalid_api_key`?** The key doesn't match any account, or the account is disabled. Re-copy it from your profile page — keys are long and easy to truncate when copy-pasting.
- **Getting `plan_required`?** Your key is valid, but your account is on the Free plan. Upgrade to Basic or above to use v1.
- **Getting a connection error, not a JSON response?** Double-check the URL starts with `https://imagetotable.ai/api/v1/` and that you're using `-X POST` (or the right verb) for endpoints that require it — a GET request to a POST-only endpoint won't reach the route at all.
- **Uploading a file and getting an unexpected error?** Multipart file uploads need `-F "file=@/path/to/file.jpg"` (curl's form-upload flag), not `-d` or a raw JSON body — mixing these up is the most common upload mistake. The leading `@` tells curl to read that path as a real file *on your own machine* — it isn't a URL, and the file has to already exist there before you run the command. If you don't have a local file handy, skip this entirely: pass a `url` field instead of `file` and the server fetches it for you — see [Quickstart](/developers/quickstart).
- **Getting `rate_limit_exceeded`?** See [Rate Limits](/developers/guides/rate-limits) — limits are per-account, not per-request-type-you-expect, so a burst of polling calls can trip the same limit as a burst of uploads.

---

Source: https://imagetotable.ai/developers/environment-setup