How to create and manage Scoped API keys

Scoped API keys let you control exactly which meetings and data an integration can access. Use scoped keys when setting up new integrations or tightening access for existing ones.

Each scoped APII key you create has a specific scope that defines precisely which meetings and related data it can access. This lets you:

• Give a third-party integration only the data it genuinely needs.
• Issue a key tied to a specific user's meetings for personal automations like Zapier.
• Prevent private recordings from ever being exposed through a key.
• Reserve broad org-wide access for the integrations that specifically require it.

This article is useful for admins who need to enforce data boundaries, protect private recordings, or limit third-party tools to only the data they need. 

Key sections

• The four scopes: Choose the right access level for your integration
• Legacy keys: Understand how older keys work and when to migrate
• Create a scoped API keys: Step-by-step to generate a new scoped key
• Manage API keys: View, rename, revoke, or regenerate existing keys

The four scopes

When creating a key you choose one of four scopes. As a rule of thumb: pick the scope that grants the minimum access the integration needs.

Scope	Tied to	What it can access	Best for
User – limited access	One user	That user’s non-private meetings only. Private meetings are always excluded.	Tools that should never receive private recordings.
User – full access	One user	Everything that user can see in Avoma, including their private meetings.	Integrations that need to act as a specific person.
Organization – limited access	Org-wide	All non-private meetings across the org. Private meetings are excluded.	Reporting or analytics tools that should only use shared data.
Organization – full access	Org-wide	All meetings the org’s licenses and settings allow, including private ones.	Central integrations that need the widest org view your policy permits.

Scope details

1. User – limited access

The key is tied to one designated user (the owner). It returns only that user’s meetings, and private meetings are always excluded.

• Owner required: You assign a specific user when creating this key.
• Private meetings: Excluded. The integration will never see recordings marked as private.
• Use when: A tool should work on behalf of one user but must never access private recordings — for example, a Zapier automation that only processes shared calls.

2. User – full access

The key is tied to one designated user. It returns everything that user can see in Avoma, including private meetings.

• Owner required: You assign a specific user when creating this key.
• Private meetings: Included. The integration can access all meetings the user is entitled to view.
• Use when: An integration needs to fully replicate what a specific user can access — for example, a personal AI assistant or analytics workflow.

3. Organization – limited access

The key has org-wide access but is limited to non-private meetings. It is not tied to a single user.

• Owner: The admin who created the key is recorded as owner for audit purposes. Data access is org-wide, not user-specific.
• Private meetings: Excluded. The integration will only ever see non-private org meetings.
• Use when: You want to connect a reporting tool, BI dashboard, or analytics platform to shared org data without ever exposing private recordings.

 

4. Organization – full access

The broadest scope available. The key has org-wide access and includes meetings your org’s licenses and policy allow, including private ones.

• Owner: The admin who created the key is recorded as owner for audit purposes.
• Private meetings: Included, subject to your org’s license and privacy settings.
• Use when: A central integration genuinely requires access to the full meeting corpus — and you have explicitly approved that level of access.

 

Legacy keys

API keys created before scoped keys were introduced are automatically tagged as Legacy in the Developer page.

• They keep working: Legacy keys are not disabled. Existing integrations using them continue to run without any changes required.
• They are read-only in the Developer page: You can view and revoke legacy keys, but you cannot assign a scope or owner to them.
• They retain full org access: Legacy keys behave exactly as they did before — they can read all meetings in your organization.
• They cannot be converted: There is no in-place migration to a scoped key. To restrict access, create a new key with the scope you need, update your integration to use it, then revoke the legacy key when you’re ready.

Constraints and limits

Constraint	Details
Scope is permanent	A key’s scope cannot be changed after creation. To use a different scope, create a new key and revoke the old one.
Issued-to user is permanent	For user-scoped keys, the “Issued to” user cannot be reassigned after creation. Create a new key to change the owner.
10 keys per org	Your organization can hold up to 10 API keys at a time. Revoking a key frees a slot immediately.
Admins only	Only org admins can create, view, or revoke keys. Non-admin users do not have access to the Developer page.

Step-by-step

Create a scoped API key

1. Go to Settings → Organization → Developer.
2. Click Add API Key.
3. Enter a descriptive Name (e.g., “Zapier – CS Team” or “BI Dashboard Readonly”).
4. Select a Scope from the dropdown:
   • User – limited access
   • User – full access
   • Organization – limited access
   • Organization – full access
5. If you selected a User scope, choose the user in the Issued to field.
6. Click Create.
7. Copy the full key string (CLIENT_KEY:CLIENT_SECRET) and store it securely.

Manage existing keys

1. View all active API keys, including their scope, owner, and creation date, in Settings → Organization → Developer.

2. To copy an existing key, go to Settings → Organization → Developer and copy it directly from the key list. 
3. To rename a key, find it in the list, click the pencil icon, and update the label. Renaming does not affect the key's credentials or any active integrations using it.
4. To delete a key, find it in the list and click on the Delete icon. This is permanent and immediately revokes access for any integration using that key.
5. To regenerate a key, find it in the list and click on the Regenerate API key button. 
   

 

Troubleshooting and FAQs

What should I do if an API key is compromised?

Regenerate it immediately — this issues a new credential without affecting other keys or losing the key name.

1. Go to Settings → Organization → Developer
2. Find the compromised key and click Regenerate
3. Copy the new credential string and update it in any integrations that were using the old key

Alternatively, you can delete the key and create a new one — but regenerating keeps the same name and is faster.

 

Can I change the scope of a key after it’s been created?

No. Scope is fixed at creation and cannot be modified. Create a new key with the scope you need, update your integration to use it, then revoke the original.

 

Can I reassign the “Issued to” user on a user-scoped key?

No. For User – limited access and User – full access keys, the assigned user is permanent. If the user leaves or you need different access, create a new user-scoped key for the relevant user.

 

What happens if the user on a user-scoped key is deactivated?

API requests using that key will return an error. The key is not automatically deleted — an admin should revoke it manually to keep the key list clean.

 

My integration is still using a legacy key. Do I need to do anything now?

No immediate action is required. Legacy keys keep working as normal. Whenever you are ready to move to tighter access control, create a new scoped key, update the integration, and revoke the legacy key.

 

We’ve reached the 10-key limit. What do I do?

Review the key list and revoke any keys that are no longer in active use. Each revoked key frees a slot immediately. We are actively exploring options to raise or remove this limit in a future update.

 

Who can see the API key values in the Developer page?

Any org admin can open the Developer page and view key strings. If a key is compromised, revoke it immediately from Settings → Organization → Developer and create a replacement.

What's next

• Getting started with Avoma's API — Overview of what the API can do and how to make your first request.
• Avoma API reference — Full technical documentation including endpoints, authentication details, and rate limits.

Recap

Your API keys are created, named, and stored securely. Each integration now has its own credential, so you can manage access cleanly as your stack grows.

Need help? Reach out at help@avoma.com.