Sonar API keys let your own systems and third-party integrations talk to Sonar securely — for example, to read loan data, generate documents, or push updates through the Sonar API or MCP tools. This article covers how to generate a key, decide who it acts as, choose its permissions, and manage keys over time.
Note: Only users with Administrator permissions can generate API keys. Support users can view existing keys. Treat every key like a password — anyone holding it can act against your Sonar data within the permissions you grant.
Before you start
Know what the integration needs to do (for example, "read loans and generate pre-approval letters" vs. "read pricing only"). You'll grant only those permissions.
Decide who the key should act as — a specific user, or your company as a whole. See Choosing an owner below.
You can only grant permissions you already have. If your integration needs something you can't grant, ask another admin who holds that permission to create the key.
Generate a key
Go to Settings → API Keys.
Click Generate API Key.
Enter a Name that describes what the key is for (for example, "LeadMailbox – production"). A clear name makes keys easy to find and revoke later.
(Optional) Set an Expiration date. After that date the key stops working automatically. Leave it blank for a key that doesn't expire.
In Assign to a user, either search for and select a user, or leave it empty for a company-level key. (See Choosing an owner.)
Under Permissions, expand the permission groups and check the specific permissions the key should have. (See Choosing permissions.)
Click Generate.
Copy the key value now and store it somewhere safe. For security, Sonar shows the full key only once at creation — afterward the list shows a masked value you cannot reveal again. If you lose it, revoke the key and generate a new one.
Choosing an owner: user-level vs. company-level
The Assign to a user field decides whose authority the key carries.
User-level key (a user is selected) | Company-level key (left empty) | |
Acts as | That specific user | Your company (no individual user) |
Permission ceiling | The key can do at most what that user is allowed to do — even if you check more, the extra permissions are ignored | Governed only by the permissions you grant; there is no user to limit it |
Loan access | Follows the user's own loan access (their assigned loans plus anything their role can see) | Can reach any loan in your company for the permissions granted |
Best for | Integrations that should be limited to one person's scope, and whose actions should be attributed to that person | Company-wide, system-to-system integrations that shouldn't depend on any one employee's account |
Why this matters: A user-level key automatically shrinks if that user's permissions are reduced, and its actions are attributed to that user in your records. A company-level key keeps working regardless of staffing changes, but it is only as safe as the permissions you give it — so grant the minimum it needs.
Choosing permissions (scopes)
Permissions are grouped by area (for example, Loans, Pricing, Documents, Credit). Expand a group and check only the permissions the integration actually needs — this is the single most important security step.
A few things to know:
You can only grant what you hold. The list is limited to permissions on your own account, so you can never create a key more powerful than you are.
Some permissions are read vs. write. Granting the ability to view loans does not grant the ability to change them — pick each deliberately.
A few internal permissions aren't grantable to keys (they only govern in-app screens). If you don't see a permission you expected, it isn't available for API keys.
One key works everywhere. The same key authorizes both the Sonar Web API and Sonar's MCP tools — you don't need separate keys for each.
Use the key
Send the key on each request in the x-api-key header:
x-api-key: <your-key-value>
Every request is checked against the key's permissions (and, for a user-level key, against that user's own permissions). If a key tries something outside its permissions, the request is rejected and nothing is changed.
Manage existing keys
On the API Keys list you'll see each key's name, a masked key value, its owner ("Company" or the user's name), how many permissions it carries, and a status of Active or Revoked.
Edit a key's permissions at any time — open it from the list and change which permissions it carries. The change takes effect on the key's next request; the key value doesn't change, so your integration keeps using the same key.
Revoke a key when an integration is retired or a key may have been exposed. Revoking takes effect right away — the key stops working on its next request. Revoking cannot be undone; generate a new key to restore access.
Rotate keys periodically by generating a new one, updating your integration, and revoking the old one.
Expiration (if you set one) revokes the key automatically on that date.
Frequently asked questions
Should I create a user-level or a company-level key?
Use a user-level key when the integration should be limited to one person's access and its actions should be attributed to them. Use a company-level key for system-to-system integrations that need to run regardless of staffing changes. When in doubt, start user-level — it's the more limited option.
What happened to the API keys I created before this release?
They keep working. Existing keys were carried over as company-level keys with the access they already had, so your integrations don't break. You can review any key on the API Keys list and tighten its permissions at any time.
Can I change a key's permissions after I create it?
Yes. Open the key from the API Keys list and update which permissions it carries. The change takes effect on the key's next request — you don't need to reissue the key or update the key value in your integration.
Do I need separate keys for the Sonar API and the MCP tools?
No. One key works for both — the permissions you grant apply everywhere the key is used.
Can I see a key's full value again later?
No. Sonar shows the full value only once, at creation. Afterward the list shows a masked value. If you've lost it, revoke the key and generate a new one.
How quickly does revoking a key take effect?
Immediately — the key stops working on its next request. Revoking can't be undone, so generate a replacement first if the integration still needs access.
Troubleshooting
Symptom | Likely cause | What to do |
Requests suddenly return 403 / not permitted | The key lacks the permission for that action, or (user-level) the assigned user's permissions were reduced | Confirm the key's permissions; for a user-level key, check the user's role. Generate a new key with the right permissions if needed. |
A permission you need isn't in the list | You don't hold that permission, or it isn't grantable to API keys | Have an admin who holds it create the key, or confirm it's an in-app-only permission. |
The full key value isn't shown anymore | Sonar shows it only once, at creation | Revoke the key and generate a new one; copy the value immediately. |
An old integration stopped working after this release | Existing keys were migrated to company-level with their prior access; a later scope change may have narrowed it | Review the key on the API Keys list and re-grant any needed permissions, or generate a fresh key. |