Authentication and API Keys

Your API Keys are the gateway to your account. Treat them with the same care as your database password.

Where to generate them

Turn on Developer mode (Your account › Preferences) and open the API keys tab of the Developers Workbench, the pill that appears in the bottom corner of the screen (/app?wb=api). There you create new keys, pick their scope (read or write), and revoke them. The secret key is shown only once when created; store it in a secrets manager, never in source code.

Authentication

The API is REST over HTTPS. Every request carries your key in the Authorization header:

curl https://cordhq.app/api/v1/me \
  -H "Authorization: Bearer sk_live_your_key"

Response:

{ "org": { "id": "...", "nombre": "Your Business", "plan": "pro" }, "scope": "write", "mode": "live" }

Environments (Live vs Test)

When you create a key you choose its mode:

• Test (sk_test_...): does not consume your API usage meter or count toward billing. Operates on your account’s test environment (a mirror organization, isolated from your real data — the same mechanism as the “Test environment” switch on the organization switcher). The first call with a test key creates that mirror organization if it doesn’t exist yet. Whether CFDI stamping is real or simulated depends on whether you have your CSD connected, not on the key’s mode. See Testing Cord without affecting production.
• Live (sk_live_...): use it in production. Every call counts toward your plan usage.

Scopes

• Read (read): query quotes, clients, products, and receivables.
• Write (write): can also create quotes, clients, and products.

Authorized connections

Zapier and Make do not use keys: they connect with one click on a Cord screen. Each connection shows up in the same list as an Authorized connection, with the app’s name, and does not count toward your plan’s number of keys. To cut an app’s access, revoke its connection just like a key; the app will ask you to authorize it again.

Key Rotation

If a key leaks (e.g. accidentally pushed to GitHub), or it is simply time to change it:

1. Open the API keys tab of the Workbench (turn it on in Your account › Preferences if you don’t see it).
2. Click Roll on the key. Cord generates a new key and lets you choose how long the old one keeps working: not at all, 1 hour, 24 hours or 7 days, so you can update your servers without cutting traffic.
3. If the key was exposed, roll it with no grace period or revoke it: revocation is immediate and any request with that key returns 401.