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 Work Profile. Full Email Marketing Access is the default for a general-purpose agent. Choose Reporting, Subscriber Management, Content And Capture, Broadcasts, Sequences, Automations, Subscriber Import And Export, Email Delivery Setup, or Outbound Webhooks when the integration has a narrower job. Choose Custom Permissions when no Work Profile fits.
9. If you choose Custom Permissions, select only the actions that the integration must perform. Read each description before selecting a permission.
10. Choose Expiration. Select an expiration date for a temporary key. Select Never expires only for long-running systems that your team actively owns.
11. Click Generate.
12. Keep the drawer open while Mailrith creates the key.
13. 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 old key with an active key that has a new secret value. Revoking a key disables access so the key can no longer be used. Revoked and replaced keys disappear from the API Keys list.

• 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.
• 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.
9. After Mailrith confirms the change, the revoked key disappears from the list.

Review Authorized Apps

Active 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, and the authorization time.

Before you approve an app, choose the workspace and Work Profile, then open Permissions to review a simple summary of its access. Choose Choose Exact Permissions only when you need a custom set. Permissions marked Optional can be cleared when the app supports partial access. Open Technical Details only when you need to check the app ID, Mailrith resource, redirect destination, or access expiration.

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. In the Access column, click the permission link, such as View 12 permissions, when you need to inspect every permission. Leave it closed for a compact list.
6. Click Revoke for any active app that should no longer access the workspace.
7. Confirm the revoke action in the Revoke Authorized App dialog.
8. After Mailrith confirms the change, the revoked app disappears from the list.

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.
• Use Full Email Marketing Access for a general-purpose agent. Give a purpose-built integration a focused Work Profile or custom permission set that matches its narrower job.
• 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.