Create an API key
A walkthrough for creating your first Invoance API key, setting it as an environment variable, and making an authenticated request. Takes about three minutes.
Already familiar with the key model and just looking for headers and scopes? See Authentication.
Before you start
Step 1 — Sign in
Open your dashboard at https://app.invoance.com and sign in.
Step 2 — Open API & Access
From the left sidebar, expand Organization and click API & Access. Or jump straight to:
https://app.invoance.com/dashboard/profile?tab=tokens
Step 3 — Create the key
Click Create key. Fill in:
Click Create.
Step 4 — Copy the key
The key is shown once. There is no way to recover it later.
Invoance stores only a cryptographic hash. If you close the dialog without copying it, the key is gone — you'll have to revoke it and create a new one.
The key looks like:
invoance_live_XXXXXXXXXXXXXXXXXXXXXXXX
Click the copy button. Paste it into your password manager (1Password, Bitwarden, your team vault) right now — not into a text file, not into Slack, not into a commit. If it leaks, revoke it and create a new one.
Step 5 — Set it as an environment variable
Don't paste the key into source code. Export it as an environment variable instead:
export INVOANCE_API_KEY=invoance_live_XXXXXXXXXXXXXXXXXXXXXXXX
$env:INVOANCE_API_KEY = "invoance_live_XXXXXXXXXXXXXXXXXXXXXXXX"
INVOANCE_API_KEY=invoance_live_XXXXXXXXXXXXXXXXXXXXXXXX
Add .env to your .gitignore if it isn't already.
Step 6 — Make your first request
Anchor a test event with curl:
curl -X POST https://api.invoance.com/v1/events \
-H "Authorization: Bearer $INVOANCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"event_type": "test.first_event",
"payload": { "hello": "world" }
}'A successful response returns the new event with its event_id, cryptographic hash, and signature. Store the event_id — you'll use it to verify the record later.
Prefer SDKs? See the Python and Node.js guides for the same example with idiomatic clients.
Troubleshooting
401The Authorization header is missing, malformed, or the key has been revoked. Confirm the header is exactly Bearer <key> with one space, the key starts with invoance_live_, and the key still appears as Active in the dashboard.
403The key authenticated but doesn't have the scope this endpoint requires. Create a new key with the correct scope, or ask an admin to update the existing one.
404The endpoint path is wrong, or you're hitting an old environment. Confirm you're using https://api.invoance.com and not a localhost URL from the docs.
429You've crossed the per-plan rate limit. The Retry-After header tells you how long to wait. If this happens often, upgrade or contact support.
—Revoke it from the dashboard (so a leaked copy can't be used) and create a new one. Keys are one-shot reveals by design.