Target audience: Workspace administrators and developers running service account integrations
Overview
A secret key is the credential a script, daemon, or integration uses to act as a service account. This article covers creating secret keys, choosing an expiration, replacing a secret key without interrupting your automation, and deleting secret keys. It applies to both collaborator and admin service accounts.
Create a secret key
Open the service account: In the web or desktop app, go to the Service accounts page and select the service account.
Create the secret key: Go to the Secret keys tab and create a secret key. Keep the 90-day expiration, pick a different date, or select Remove for no expiration.
Copy the secret key: LucidLink shows it once. Store it somewhere safe, such as a password manager or secrets manager.
Creating a service account in the app doesn't create a secret key. Creating one through the API creates a secret key by default.
Rotate a secret key on a linked daemon
1. Create a new secret key: In the web or desktop app or API, create a new secret key for the service account you want to rotate.
2. Run the rotation command: On the machine running the linked daemon, run the rotate-credentials command with the new secret key:
lucid [--instance N] rotate-credentials --login-token [token]3. Confirm the swap: The daemon keeps running under the new secret key without disconnecting.
4. Delete the old secret key: Once the new secret key works, delete the old one from the service account's Secret keys tab to complete the rotation.
Rotate a secret key used by a script or API integration
Create a new secret key for the service account.
Update your script or integration to use the new secret key, and confirm it works.
Delete the old secret key.
The service account's access doesn't change at any point.
Find secret keys to clean up
The secret key count in the app includes expired and used single-use secret keys. Through the API, each secret key reports a status (pending, active, consumed, or expired) and lastUsedAt. Use them to find secret keys that are expired, used up, or no longer in use, and delete them.
Frequently Asked Questions
Is a secret key the same as an identity or a login token?
Yes. The app calls it a secret key. The API calls it an identity, and the command line calls it a login token.
Can a service account have more than one secret key?
Yes. Every secret key has the same access as its service account. To give different access, create another service account.
Can I see a secret key again after I create it?
No. LucidLink shows a secret key once, when you create it. If you lose it, create a new secret key on the same service account.
Do secret keys expire?
Yes, by default. A new secret key expires after 90 days. When you create it, you can pick a different date or select Remove to make it non-expiring. You can't change the expiration after the secret key is created. To extend access, create a new secret key and rotate to it. Through the API, a secret key doesn't expire unless you set expiresAt.
Can I create a single-use secret key?
Yes, through the API, SDK, or MCP only, not in the app. A single-use secret key is used up by its first successful authentication. Rejected requests don't use it up. If you need another, create a new secret key.
Can I rotate a secret key in the app?
No. In the app, you can create and delete secret keys. To replace a secret key without downtime, follow the steps above.
Do I need to restart the client to rotate a secret key?
No. Rotation happens while your daemon stays linked and mounted. No restart or remount is required.
Can I reuse a one-time login token after rotating to it?
No. One-time login tokens are single-use. Once you rotate to one and later unlink, that same token can't be used to link again.
What happens if I try to rotate to a secret key from a different service account, or one that's expired or deleted?
Before rotating, LucidLink checks that the new secret key belongs to the same service account as the linked daemon. If it doesn't match, or the secret key is expired or deleted, the rotation is rejected and the daemon stays linked with its current secret key.
What happens when I delete a secret key?
It stops working immediately. Deleting a service account deletes all of its secret keys.