Authentication

Every request authenticates with an API key we issue to your organization.

Authorization: Bearer mag_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• The key identifies your organization — you never send an org id; it's resolved from the key. All clients, documents, and submissions you create are scoped to your org, and a key can never see another org's data.
• Keys are prefixed mag_. Treat them like a password: store in a secret manager, never commit them, never expose them in a browser.
• Both Authorization: Bearer mag_... and a bare mag_... are accepted; prefer the Bearer form.

Two kinds of key

Almost everything in these docs uses a firm key (mag_…) — the one above, scoped to a single organization, which carries client data.

Partners also get a partner key (magp_…) for managing the firms they serve and those firms' API keys. It is a different credential for a different job: it can never read or write client data, and a firm key can never call the partner endpoints — each is rejected with 401 on the other's surface. Its scopes are partner.read, partner.keys.write and partner.firms.write, set when the key is created in the partner console. See the Partner API.

Scopes

A firm key created in the portal — self-managed or partner-issued — carries the full set below, so it can drive the whole loop out of the box (per-scope tailoring isn't self-serve today). Partner keys are the exception: the console offers a choice at creation — a view-only key carries partner.read alone, a management key carries partner.read, partner.keys.write and partner.firms.write — see the Partner API.

A request to an endpoint you're not scoped for returns 403. GET /v1/organization echoes a key's scopes so you can confirm.

Check your key

curl -s https://api.magnetictax.com/v1/organization \
  -H "Authorization: Bearer $MAGNETIC_API_KEY"

{
  "organization_id": "org_…",
  "owner": "Your Firm LLC",
  "scopes": ["clients.read", "clients.write", "documents.write", "submissions.read", "submissions.write"],
  "default_tax_software": "Drake",
  "sandbox": false
}

• owner — who this key acts as: your firm's name for a firm-direct key, or the partner's name for a partner-issued key.
• scopes — a self-managed key created in the portal carries the full integrations scope set shown above.
• default_tax_software — informational only; tax_software is still required on every submission.
• sandbox — true when this key's submissions run in sandbox: either a sandbox key or a key in a sandbox organization (its submissions never reach a real preparer). Check it to confirm you're pointed at sandbox before firing real submissions.

You create and manage your own API keys in the Magnetic portal: a firm admin under Preferences → Self-managed API, or a partner from the partner console. Live and sandbox keys are both created there — a sandbox key just flags its submissions as test (see Sandbox testing). The key itself is shown once at creation; the portal shows a webhook signing secret only when key creation — or a later update — sets a webhook URL. Questions or need help? Talk to your Magnetic contact.

Signing secret: a key's whsec_… webhook signing secret is issued only when the key has a webhook URL, and it's rotated (a new secret shown once) whenever you set or change that URL — see Webhooks → Signing secret. Capture the new value each time; the previous one stops verifying.

Rotating a key or a lost signing secret: the key itself can't be re-displayed after creation. If a key is compromised, create a new key (and set its webhook URL), point your integration at it, then revoke the old one. If you only lost the signing secret, you need the URL to actually change — re-saving the same URL is a no-op and reveals nothing. Either point the key at a different URL, or clear the URL (save blank) and then set it again; the second save issues a fresh secret and shows it once.