Manage integration API keys

API keys let an external system read a limited part of your organisation without sharing a person's account. Only owners and administrators with the right permissions can create or manage them.

Open Integrations, then API keys. A key belongs permanently to the organisation shown in the workspace header. It cannot log in to the web app or write records, and it cannot read another organisation.

Create a key

Select Create API key.
Give the integration a name that identifies the consuming system and environment. Add a purpose so another administrator can understand why it exists.
Select only the read scopes the external system needs.
Keep the default 90-day expiry, choose another future expiry within one year, or deliberately select No expiry. Non-expiring keys require continuing review and prompt revocation when no longer needed.
Review the exact scopes and expiry, then confirm creation.

Metra shows the full secret once. Copy it directly into a secrets manager or password manager. Do not put it in source control, screenshots, tickets, chat, email, URLs, or a normal document file. You must confirm you saved it before closing the panel because Metra never shows it again.

If the secret is lost, rotate the key or create a replacement. Metra cannot reveal it again.

Understand the key list

The list shows safe metadata only: name, display prefix, scopes, lifecycle status, expiry, and approximate last-used time. It never shows the full secret.

Active keys can authenticate until expiry or revocation.
Expired keys remain in lifecycle history but cannot authenticate.
Revoked keys cannot be restored or used again.

The last-used time may be delayed because usage updates are aggregated. Treat Never as a useful review signal, not proof that no request was attempted.

Rotate a key

Select Rotate for an active key and choose a cutover:

24-hour overlap keeps the previous secret valid for 24 hours while you update and verify the integration.
Immediate cutover deactivates the previous secret as soon as rotation completes. Use this if the current secret may be compromised.

Rotation does not broaden scopes or extend the key's expiry. Store the new one-time secret before leaving the panel. After an overlap migration, remove the previous secret from the consuming system before its retirement time.

Revoke a key

Select Revoke, enter the operational or security reason, and confirm. Revocation is immediate and irreversible. Create a separate replacement explicitly if integration access is needed later.

Revoke credentials promptly when an integration is retired, ownership is unclear, a secret may have leaked or the requested access is no longer justified.

Troubleshooting

If Integrations is missing, ask an owner or administrator to review your organisation permissions.
A rejected request may mean the key is expired, revoked, not for this organisation, missing a required scope, or hitting a rate limit.
Confirm the integration sends the secret only in the Authorization: Bearer header.
Share the response request ID with support. Never send the key or complete authorization header.