API keys

Use API keys and API key secrets to securely authenticate API requests to NS1 Connect API keys define access permissions, while API key secrets are the tokens used to authenticate API requests. NS1 Connect supports API key secret expiration and rotation to help maintain secure and uninterrupted access.

API keys provide authenticated access to NS1 Connect features and API operations. Depending on the assigned permissions, API keys can be used to perform all the operations available in the web-based interface.

API key and API key secrets

In NS1 Connect, API keys and API key secrets are treated as separate objects. Every API key is associated with at least one valid API key secret. When you configure an expiration date for an API key, the expiration date applies to the associated API key secrets and not the API key itself. If all associated API key secrets expire, the API key becomes invalid.

API keys can also be configured without expiration dates and remain valid indefinitely. However, for security purposes, it is recommended to configure API key secrets with expiration dates and rotate API key secrets regularly. API keys configured without expiration dates do not support API key secret rotation.

Each API key secret also has a unique secret ID that is separate from the API key secret itself. The secret ID identifies the API key secret but cannot be used to authenticate API requests.

API key secret expiration and rotation

When an API key secret approaches its expiration date, you can rotate the API key secret to generate a new secret with a new expiration date without immediately invalidating the previous API key secret. When you rotate a secret through the API, the existing API key secret is used in the request that generates the new secret. For more information, see Generate new API key secret. Because NS1 Connect supports up to two valid API key secrets for a single API key, teams can continue using existing services and integrations while applications and automation workflows are updated with a new API key secret. This helps maintain continuous access and reduce service disruptions caused by expired or replaced credentials.

API key rotation and secret expiration provide the following operational and security benefits:

Fine grained access control where administrators can provide teams, applications, or integrations with only the API key secrets required for their specific operational or project based use. Thus, allows teams to independently rotate only their assigned API key secret without broader access to other API keys in the account. For more information, see Generate new secret for current API key.
Temporary or project based access where administrators can configure API key secrets with limited validity periods, so that access automatically expires when it is no longer required. This helps reduce the security risks associated with long lived credentials. For more information, see Creating API keys.
Reduced reliance on the web-based interface. API key creation, API key secret rotation, expiration management, and granular access control can be performed directly by using the API. This also allows teams to rotate their assigned API key secrets without requiring broader permissions such as the Manage API keys permission.
Recovery or emergency access scenarios where users with Manage API keys permission can restore or extend API key secret access if an API key secret expires prematurely, or access must be temporarily reenabled. For more information, see Edit API key secret.

Note: Expired API key secrets are retained for twice their configured expiration duration before they are permanently deleted. A minimum retention period of 60 days and a maximum retention period of 180 days apply. For example, a secret with a 7-day expiration duration is retained for 60 days after expiration, while a secret with a 120-day expiration duration is retained for 180 days after expiration

For more information about performing API key and API key secret management tasks by using the API, see API keys.