API keys provide programmatic access to approved Builder or service APIs. Create a key only for a defined integration, scope it to the smallest set of endpoints and permitted network locations, and store the secret in an approved secret manager.

An API key is a credential, not a general-purpose identifier. Anyone holding its secret can act with the permissions the key has.

Plan the key before creating it

Record the integration owner, consuming system, exact API operations, permitted source IP addresses or CIDR ranges, environment and rotation process. If any of these are unknown, do not create the key yet.

flowchart LR
  A[Documented integration need] --> B[Least-privilege endpoint scope]
  B --> C[Approved network range]
  C --> D[Create API key]
  D --> E[Store secret once in secret manager]

Do not share a single key between unrelated systems. Separate keys make revocation, audit and ownership clearer.

Create and store a key safely

1. Open the library’s API-key settings.
2. Create a key for one named integration.
3. Choose only the required API endpoints.
4. Add the permitted source IP addresses or CIDR ranges and a description for each where available.
5. Create the key and copy the secret immediately into the approved secret manager.
6. Configure the consuming system from that secure store.
7. Test only the intended API operations from an approved source.

The key secret is displayed only once. Do not put it in a ticket, chat message, document, source repository, browser screenshot or plain-text configuration file. If it is lost, create a replacement rather than trying to recover it.

Apply least privilege

Allowed endpoints define what the key can do. Grant the smallest set that the integration requires. Allowed IP addresses limit where it can be used from; specify the known service address or narrowly defined network range rather than a broad public range.

The current permission list separates submitted-data access, analytics reads, service deployment and version checks, service-definition updates, library and service reads or writes, and Darcy or agent operations. Read, write, deployment and agent permissions are independent. Do not select a whole family merely because the client may need one operation later.

An IP allowlist is strongly recommended but is not mandatory. Enter an exact IPv4 or IPv6 address, or a CIDR range. Do not include a protocol, port or hostname. Add a description that identifies the approved workload or network owner.

Review the key’s settings when the integration changes. A key that once needed a broad endpoint set or network range should be tightened when the dependency becomes more specific.

Rotate and revoke keys

Plan rotation before a key is deployed. Create a replacement, update and test the client, verify successful use, then revoke the old key. Keep the overlap as short as practical and coordinate the change with the integration owner.

Revoke a key immediately when it is no longer needed, its owner leaves, the consuming system is retired, or exposure is suspected. Revocation stops future use; investigate logs and rotate any related credentials according to the incident process.

Monitor ownership and use

Use the key’s audit information to identify who created it and whether it has been used. Review inactive or unknown keys regularly. A key without a current owner should be treated as a candidate for revocation, not as a harmless historical setting.

Test checklist

• The key maps to one documented integration and owner.
• Allowed endpoints are no broader than required.
• Allowed IP addresses or CIDR ranges are narrow and current.
• The secret was stored securely when first displayed and never copied into documentation or source control.
• The client succeeds only from approved infrastructure.
• A rotation and emergency-revocation process is documented and tested.
• Inactive and ownerless keys are reviewed regularly.

Related guidance

• Library settings
• API actions
• Service authentication and user access
• Library integrations and data