API docs / Get started

Authentication

Every request authenticates with an API key that belongs to your organization.

Sending your key

Send the key as a bearer token on every request. The examples read it from the EQUITY_MATRIX_API_KEY environment variable:

curl https://api.equitymatrix.io/v1/members \
  -H "Authorization: Bearer $EQUITY_MATRIX_API_KEY"

The header is Authorization: Bearer followed by the key, which starts with em_live_. A missing, unknown or revoked key gets a 401 with the error code invalid_api_key.

How keys work

  • Keys belong to the organization, not to the person who created them. A key keeps working if its creator leaves the organization or stops being an admin.
  • The organization comes from the key. You never pass an organization ID, and a key can only see and change its own organization’s data.
  • A key can do what an admin can do with contributions, but only through the API at https://api.equitymatrix.io/v1. It isn’t a user account, and it can’t sign in to the app or reach anything else.
  • Only active admins can manage keys. Admins create and revoke keys under API Keys in the account menu. An organization can have up to 10 active keys, and a key’s name can be up to 50 characters.
  • The full key is shown once, when it’s created. Equity Matrix stores a hash of it and the first few characters for display, never the full key. If you lose a key, revoke it and create a new one.
  • Revoking takes effect on the next request. Contributions a key already sent stay in your vault.

Keeping keys safe

  • Store keys in your tool’s secrets or credentials settings, not in code you share.
  • Use one key per tool, like Odoo and Harvest. Then each contribution shows where it came from, and you can revoke one tool’s access without touching the others.
  • If a key may have leaked, revoke it right away. You can revoke keys even while your plan is inactive.

Plan status

The API works while your Equity Matrix plan is active or in its trial. If the plan lapses, is past due or is cancelled, requests with an active key get a 402 with the error code plan_inactive, and admins can’t create new keys. Keys aren’t revoked, though. They start working again on their own when the plan is active again.