API keys

API keys are authentication credentials that let you access SuperAnnotate through the API and SDK. They can be used by scripts, integrations, pipelines, and other automated workflows that need to interact with SuperAnnotate.

API keys are scoped to an individual team member, to the team or the organization:

• Organization API keys belong to the organization rather than an individual member. These keys can perform organization-level and team-level actions, including creating and deleting teams, managing integrations and team member permissions, and accessing actions available through Team API keys. They can also be used to generate and rotate Team API keys.
• Team API keys belong to the team rather than an individual member. They provide team access similar to Team Admin permissions and are useful for shared automations and integrations that should continue working independently of the person who created the key. Team Admins must be granted the Access team API keys permission to access these keys. These keys are designed to be used in custom actions of Orchestrate pipelines, as described here.
• Personal API keys are tied to the member who creates them and use that member's permissions. This lets Team Owners and Team Admins authenticate with their own credentials while keeping API access aligned with their existing access in the team. Personal API keys are automatically revoked when their owner leaves the team.

API keys management capabilities depend on your role and assigned permissions:

• Organization/Team Owner can generate organization, personal, and team API keys. The Owner has full key-management access and can generate, view, rotate and revoke any type of a key, as well as other users’ personal API keys revocation.
• Team Admin can generate and manage their own personal API keys by default. The Owner can additionally grant Team Admins permission to:
  • generate and manage team API keys with the Access team API keys permission;
  • revoke other members’ personal API keys.
• Team Contributor doesn’t have access to any type of API key management.

API keys can be viewed and managed in:

• Organization API keys: Organizations > Settings > Security > API Keys
• Team & Personal API keys: Team Setup > Security > API Keys

All types of keys can be given an expiration date and can be rotated when they need to be replaced, and revoked. Rotation lets you create a replacement key while temporarily keeping the original key valid, helping you update applications and services without interrupting access.

API key statuses

---

Organization API Keys

Organization API keys provide organization-level authentication for the SuperAnnotate API. They are bound to the organization rather than an individual user and can only be generated and managed by the Organization Owner.

Organization API keys can perform organization-level and team-level actions, including creating and deleting teams, managing integrations and team member permissions, and accessing actions available through Team API keys. They can also be used to generate and rotate Team API keys.

Team API keys

Team API keys provide team-level authentication for the SuperAnnotate API and SDK. They are bound to the team rather than an individual member, making them suitable for team-wide actions.

Team Owners can access the Team API Keys section and manage all Team API keys, not just the ones they created. Team Admins can do the same when they have the Access team API keys permission.

The Team API Keys table displays information about each key, including its name, status, creator, creation and expiration dates, last usage, and revocation details.

Team API keys can also be used for automated access when configuring pipelines in Orchestrate.

Personal API Keys

Personal API keys provide authenticated access to the SuperAnnotate API and SDK for an individual team member. A Personal API key is bound to the member who creates it and is scoped to the team where it was generated.

Personal API keys inherit the permissions granted to their owner based on their role. For Team Admins, this includes any additional Team Admin permissions assigned to them.

Team Owners and Team Admins can view their own Personal API keys details. Team Owners can also view Personal API keys details created by other Team Admins. Team Admins with the Revoke members' personal API keys permission can view Personal API keys details created by other Team Admins and the Team Owner.

The Personal API Keys table displays information about each key, including its name, status, creation and expiration dates, last usage, and revocation details.

---

Generate API keys

To generate an API key:

1. Go to the corresponding tab for the API key you want to generate:
   • Organization API Keys
   • Team API Keys
   • Personal API Keys
2. Click + Generate.
3. Enter a name for the key (max 120 characters).
4. Select an expiration period:
   • 30 days
   • 60 days
   • 90 days
   • 365 days (Default)
   • Custom – any period of time up to 365 days.
5. Click Generate.
6. Copy the generated API key and store it securely. An API key value is shown only once, immediately after it is generated or rotated. Once you close the pop-up, the value cannot be viewed again by anyone, including the Team Owner.
7. Click Done and the generated API key will appear in the list with the Active status.

Rotate API keys

Rotating an API key creates a replacement key while optionally keeping the original key valid for an overlap period. This gives you time to update applications or services to use the new key without interrupting access.

Only keys with an Active status can be rotated.

To rotate an API key:

1. In API Keys, go to the tab that contains the key you want to rotate:
   • Organization API Keys
   • Team API Keys
   • Personal API Keys
2. Find the API key and click the three dots ⋮.
3. Select Rotate.
4. Select an expiration period for the new key.
5. Select an Overlap period, which can’t extend beyond the expiration of the new key:
   • Expire immediately – the original key stops working immediately and its status is changed to Expired.
   • 24 hours
   • 7 days (Default)
   • 14 days
   • 30 days
6. Click Rotate.
7. Copy the new API key and store it securely. An API key value is shown only once, immediately after it is rotated. Once you close the pop-up, the value cannot be viewed again by anyone, including the Team Owner.
8. Click Done.

The new key becomes active immediately and appears in the list with the same name as the original key. The original key remains in the list with the Rotating status.

Revoke API keys

Revoking an API key permanently invalidates it. Only keys with an Active or Rotating status can be revoked. Team Owner and Team Admins with Revoke members' personal API keys permission can revoke Personal API keys created by other Team Admins and the Team Owner.

To revoke an API key:

1. In API Keys, go to the tab that contains the key you want to revoke:
   • Organization API Keys
   • Team API Keys
   • Personal API Keys
2. Find the API key you want to revoke and click the three dots ⋮.
3. Select Revoke.
4. In the pop-up, click Revoke.

To revoke multiple API keys at once:

1. Click on the checkbox beside each of the keys you want to revoke.
2. In the floating bar, click Revoke.
3. In the pop-up, type “revoke” in the confirmation field. This field is case sensitive.
4. Click Revoke.

Revoked keys stop working immediately and cannot be restored or reactivated. Applications, scripts, or other tools using a revoked key can no longer authenticate with it.

Expiration reminders

Expiration reminders are sent 14 days, 7 days, and 1 day before an active or rotating key expires. Personal API key reminders are sent to the key owner, while the Organization API key reminders are sent to the Organization Owner. Team API key reminders are sent to the Team Owner and Team Admins with the Access team API keys permission.

---

API Keys table

In the Organization, Personal and Team API keys tables, you’ll see the following columns:

• Name – The key’s name.
• Owner – Personal API Keys only – The owner of the key. Only visible to the Team Owner, and Team Admins with the Revoke members' personal API keys permission.
• Status – The status that the key is in.
• Created by – Organization and Team API Keys only – The user who generated the key. Only visible to Team Owners, and Team Admins with the Access team API keys permission.
• Created at – The date that the key was generated.
• Expires – When the key will expire.
• Last used – When the key was last used.
• Revoked – When the key was revoked and by whom.
• More menu ⋮ – Contains the Rotate and Revoke actions depending on the key status and user role.

There are various ways you can manage these columns:

• Resize - Click and drag the edge of any column to resize.
• Freeze - To freeze a column in a static position on the left side of the table, hover over the column and click the Freeze icon in the header.
• Move - Click and drag the header of any column to move and reorder it.
• Sort - You can click the up or down arrows on a column's header to sort its corresponding data by ascending or descending order, respectively. By default, the table is sorted by Creation Date.

If you Resize, Freeze, and Move your columns, the state of the key table will be saved for you. Any time you refresh or revisit the key table, it will maintain your latest changes.

Search & Filter API keys

Use the search bar and status filters to find API keys. You can filter keys by: All, Active, Rotating, Revoked, or Expired.

In Personal API Keys, Team Owners and Team Admins with the Revoke members' personal API keys permission can also search by owner email and filter keys by: All, Me, or Others.

API keys and SSO

When SSO is required for an organization and a user has not signed in through the organization’s SSO flow, API key access behaves as follows:

• Personal API keys: Requests made using the user’s Personal API key should fail with an error.
• Team and Organization API keys: Requests made using these keys continue to work because they are bound to the team or organization, respectively, rather than an individual user.