API Keys and Authorized Apps

API Keys and Authorized Apps Are Different

Mailrith gives outside systems two ways to connect to a workspace. API keys are direct credentials that you create in Settings. Authorized apps are third-party applications that a user approved on Mailrith's OAuth authorization screen.

• Use an API key when your own website, backend, script, or internal tool needs direct access to Mailrith.
• Use an authorized app when a third-party tool asks you to connect Mailrith and sends you to a Mailrith approval screen.

Both credential types are workspace-scoped. A key or authorized app can access only the workspace it was created or approved for. You do not need to send a separate workspace choice when you use the public API because the credential already identifies the workspace.

These credentials belong to the workspace, not the person who created or approved them. Removing a Team Member does not delete, transfer, or disable them. Mailrith keeps creator and latest-authorization details only to help with security reviews.

Create an API Key

Workspace owners and teammates with Manage API Keys create API keys from Settings on the API Keys tab. Teammates with View API Keys can review the list but cannot generate, rotate, or revoke keys. Create a separate key for each integration so you can rotate or revoke one integration without affecting the others. For example, use one key for your website sign-up form, another key for a CRM sync, and another key for an imported subscriber data script. If you are building the integration yourself, create the key first, and then follow the Developer Quickstart.

1. Use the workspace selector in the left sidebar to choose any workspace owned by the account whose API keys you want to manage. The API Keys tab appears when you have API key access in at least one workspace owned by that account.
2. Click Settings in the left sidebar.
3. Click the API Keys tab.
4. Wait for the API key list to load. If Mailrith cannot load it, click Try Again. Key-changing actions remain unavailable until the list loads successfully.
5. Click Generate API Key.
6. In the Generate API Key drawer, choose the Workspace that the integration needs to access.
7. Enter a Name that identifies the system that will use the key.
8. Choose Access Level. Use Read Only for reporting or syncs that only read records. Use Read and Write only when the integration must create or change records.
9. Choose Expiration. Select an expiration date for a temporary key. Select Never expires only for long-running systems that your team actively owns.
10. Click Generate.
11. Keep the drawer open while Mailrith creates the key.
12. In the Save Your API Key dialog, copy the full key immediately. Mailrith shows the full key only once.

After you close the key dialog, Mailrith keeps enough information to identify the key, but Mailrith does not show the full secret again. If you lose the full key, rotate the key or create a new key, and then update the integration with the new secret.

Rotate or Revoke API Access

Rotating a key replaces the secret value for an API key while keeping the integration record in place. Revoking a key disables access so the key can no longer be used.

• Rotate a key when the system still needs access but the secret may have been seen by the wrong person, stored in the wrong place, or used for too long.
• Revoke a key when the integration is no longer used, a vendor relationship has ended, or you want access to stop immediately.
• Do not rotate revoked keys. After a key is revoked, create a new key if the integration needs access again.

Before you rotate a key, confirm that the person responsible for the integration is ready to update the stored secret in the connected system. Rotation is successful only after the connected system uses the new key. If the integration keeps using the old key after rotation, the integration will stop working. If that person should no longer have workspace access, remove or change their access through Team Members.

1. Use the workspace selector in the left sidebar to choose any workspace owned by the account whose API keys you want to review.
2. Click Settings in the left sidebar and open the API Keys tab.
3. Use Search API keys to find the key by name, owner, workspace, or purpose.
4. Click Rotate when the integration should keep working with a new secret value.
5. Keep the dialog open while Mailrith rotates the key.
6. Copy the replacement key from the dialog, update the connected system with the new key, and confirm the connected system works before you consider the rotation complete.
7. Click Revoke when the integration should stop working immediately.
8. Keep the dialog open until Mailrith confirms that the key was revoked.

Review Authorized Apps

Authorized apps appear on the Integrations page after an outside application connects to Mailrith through an OAuth approval flow. Workspace owners and teammates with View Integrations can review the list. Manage Integrations lets a teammate approve an app for a shared workspace or revoke an active app. The list shows the app name, the workspace the app can access, the permissions the app requested, the authorization time, and whether the authorization is active or revoked.

1. Use the workspace selector in the left sidebar to choose a workspace where you have View Integrations or Manage Integrations access.
2. Click Integrations in the left sidebar.
3. Click the Authorized Apps card.
4. On the Authorized Apps page, check the app name, workspace, access, activity, and status for each connected app.
5. Click Revoke for any active app that should no longer access the workspace.
6. Confirm the revoke action in the Revoke Authorized App dialog.

Revoke an app when your team no longer uses it. Revoking an authorized app stops future access from that app, but it does not delete Mailrith records that the app already created or updated. If you reconnect the same app later, the app must go through the authorization flow again. For account-level access review, also check Settings.

If a workspace is over the current plan's workspace limit, Mailrith blocks new app approvals for that workspace. You can still click Revoke for an active app so you can always stop access you no longer want.

Mailrith keeps one authorization for each app and workspace. If another owner or teammate with Manage Integrations approves the same app again, Mailrith updates that workspace authorization instead of creating a second one. When the app asks for the same permissions or adds permissions, the existing connection keeps working until the app finishes reconnecting. If the approval removes a permission, the older access stops immediately.

If the authorized apps list is empty, no OAuth apps are currently connected to the selected workspace. This is normal for teams that only use direct API keys.

Credential Safety Checklist

• Name each key after the system that uses it, not after the person who creates it.
• Store full API key values in a password manager, secret manager, or server environment variable. Do not paste API key values into shared documents or chat channels.
• Give each integration the smallest access level that still lets the integration do its required work.
• Review keys and authorized apps whenever a contractor leaves, an agency handoff occurs, or a connected tool is retired.
• Revoke any credential or authorized app you do not recognize. Create a new credential only if a real integration stops working and you can identify who owns the integration.