# API Keys and Authorized Apps

> API keys and authorized apps control how outside systems access a workspace. This guide explains when to use each credential type, how to create credentials safely, and when to revoke access.

- Human page: https://mailrith.com/docs/api-keys-and-authorized-apps
- Markdown page: https://mailrith.com/docs/api-keys-and-authorized-apps.md
- Category: Getting Started
- Reading time: 8 min read
- Last updated: 2026-07-28
- Related keywords: API Keys and Authorized Apps, API Keys and Authorized Apps documentation, Getting Started, Getting Started documentation, Mailrith documentation, Mailrith help, Keys vs Authorized Apps, Create an API Key, Rotate or Revoke Access, Review Authorized Apps, Credential Safety Checklist, Account Settings, Subscribers, Team Members

## AI Agent Notes
- Use this article as step-by-step Mailrith product guidance, not as legal, financial, or deliverability advice unless the article says so.
- Preserve exact Mailrith UI labels from the steps when explaining a workflow.
- Prefer Mailrith's product term Subscribers when referring to people on an email list.

## What this guide covers
Create workspace API keys with Work Profiles or custom permissions, rotate or revoke keys, and review connected OAuth apps.

## Sections
- Keys vs Authorized Apps
- Create an API Key
- Rotate or Revoke Access
- Review Authorized Apps
- Credential Safety Checklist

## Visual Reference
![Mailrith account settings page showing account-level settings.](https://mailrith.com/docs/screenshots/account-settings.png)

Settings includes API keys for direct integrations. Authorized apps are reviewed from the Integrations page.

## 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](https://mailrith.com/developers/quickstart.md).

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](https://mailrith.com/docs/team-members.md).

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](https://mailrith.com/docs/account-settings.md).

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.

## Related Guides
- [Account Settings](https://mailrith.com/docs/account-settings.md): Settings separates your personal profile, security, and account controls from the selected workspace owner's billing and workspace API keys.
- [Subscribers](https://mailrith.com/docs/subscribers.md): The Subscribers page is the main workspace for your Subscriber list. Use it to search Subscribers, filter Subscribers by status, run bulk actions, import and export CSV files, and review source-specific Subscriber history.
- [Team Members](https://mailrith.com/docs/team-members.md): Team Members gives you detailed control over which workspaces each person can access and what each person can do in those workspaces, without granting broad access to everything.