Implementing secrets rotation

When your integration provisions resources with credentials (like API keys, database passwords, or access tokens), you must implement secrets rotation to allow Vercel users to rotate these credentials securely without reprovisioning the resource.

Vercel calls your partner API to trigger a rotation. This happens when a user or admin requests secret rotation for a resource and may also be called programmatically by Vercel. Your integration then rotates the credentials either synchronously (immediately return new secrets) or asynchronously (rotate later and notify Vercel when complete).

1. The customer clicks "rotate secret" in the Vercel dashboard for a resource you manage
2. Vercel makes a request to your endpoint
3. Your backend either generates new secrets for the resource and returns them in the response or returns and performs the rotation asynchronously, calling the endpoint on Vercel to complete the rotation
4. Once Vercel has the new secrets for the resource, the customer's linked projects will be redeployed to pick up the new secrets.
5. After the period of time specified in , the old secrets should stop working and be deleted by your code

Vercel calls this endpoint on your partner API to request secret rotation:

Path parameters:

• : The Vercel installation ID (e.g., )
• : Your external resource ID that you provided when provisioning the resource

Request body:

• (optional): A string explaining why the rotation was requested
• (optional): Number of hours (0-720, max 30 days) before old secrets expire. Can be a decimal amount (ex: ).

Once you receive this request, you should rotate the secrets for this resource and keep the old ones live for the specified amount of time, to allow for linked projects to be redeployed to get the new values.

You can respond in two ways depending on your implementation:

Return the rotated secrets immediately:

• : Indicates you've completed rotation immediately
• : Array of rotated secrets with and
• (optional): Set to if only a subset of secrets are included in the response (the default is indicating your response contains the full set of environment variables for the resource)

Indicate that rotation will happen later:

When you return , you must call Vercel's API later to complete the rotation using the Update Resource Secrets endpoint:

Use the access token you received during installation to authenticate this request.

Here's a complete example of implementing the rotation endpoint:

Return appropriate HTTP status codes for error cases:

When testing your implementation:

1. Provision a test resource through your integration
2. Navigate to the resource in the Vercel dashboard
3. Click "Rotate Secrets" or similar action
4. Verify your endpoint receives the request with correct parameters
5. For synchronous rotation, confirm Vercel receives and updates the secrets
6. For asynchronous rotation, verify your background job completes and calls Vercel's API
7. Confirm the resource now displays the correct environment variables on the resource page in the Vercel dashboard
8. Confirm old credentials expire at the correct time

• Validate all inputs: Check that doesn't exceed your
• Audit all rotations: Log who requested rotation, when, and why
• Handle failures gracefully: If rotation fails, maintain old credentials and return an error
• Test credential expiration: Ensure old credentials are properly revoked after the delay period
• Support partial rotation: If you can't rotate all secrets, return with the secrets you did rotate
• Implement idempotency: Handle duplicate rotation requests gracefully
• Monitor rotation requests: Track rotation frequency to detect unusual patterns