Target audience: Workspace administrators and developers
Overview
A service account is an account that isn't tied to a person. Scripts, pipelines, and integrations use it to work with your workspace without borrowing someone's login. If a team member leaves, the automation they built keeps running. LucidLink offers two types of service accounts: collaborator service accounts and admin service accounts.
Which type do you need?
| Collaborator service account | Admin service account | |
|---|---|---|
| Access | Only the filespaces and folders you grant, with read or write | Everything a workspace administrator can do |
| Workspace API (members, groups, filespaces, service accounts) | No. Its secret key only authorizes file access to the folders you grant. | Yes |
| Where you create it | Service accounts page in the web or desktop app, through the API or MCP, or by an admin service account. | Service accounts page in the web or desktop app |
| Who can create it | Workspace Owners, Workspace Admins, Admin Service accounts | Workspace Owners, Workspace Admins |
Start with a collaborator service account whenever the job only needs certain folders. A collaborator service account can't do more than you granted it, so a leaked secret key exposes less. Choose an admin service account when the job needs workspace-wide API access, such as managing members, groups, and permissions.
Frequently Asked Questions
Can a filespace administrator create a service account or grant it access?
No. Only workspace owners and workspace administrators can create service accounts or manage their access.
Does a new collaborator service account have access to anything?
No. You grant access explicitly. Collaborator service accounts aren't members of the Everyone group, so they don't get its access. If you previously relied on the Everyone group to give a collaborator service account access, grant that access directly.
Can a collaborator service account get access through a group?
Yes. You can add a collaborator service account to a group, and it then gets that group's access, the same as a member. The Access view in the app shows only access granted directly to the service account.
Can a collaborator service account with write access delete files?
Yes. Write access includes creating, changing, and deleting files and folders.
Can a secret key have less access than its service account?
No. Every secret key has exactly the access of its service account. If you need different access, create another 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 remove the expiration. You can't change the expiration after the secret key is created. To extend access, create a new secret key and replace the old one. See Manage service account keys. Through the API, a secret key doesn't expire unless you set an expiration.
Is a secret key the same as an identity or a 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 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 instead of a new account.
Can I rename a service account?
No. Choose a name that says what the account is for.
Can a service account connect to a filespace when my workspace requires SSO or two-factor authentication?
Yes it can login despite the SSO or MFA requirement.
Are service account actions recorded in the audit log?
Yes, for file actions taken through the LucidLink client or the Python SDK. They appear under the service account's name.
Can a collaborator service account call the LucidLink API?
No. Its secret key authorizes file access when a client mounts the filespace. Calls to workspace API endpoints return 403, which is expected. Use an admin service account for those.
What happens if I delete a service account?
All of its secret keys stop working immediately. For a collaborator service account, its access grants are removed too.
What you can do with a service account
Set up a collaborator service account. See Collaborator Service Accounts (GA).
Call the LucidLink API (admin service accounts only). See Create an admin service account and authenticate with the API.
Connect an AI client through the LucidLink MCP server. See the next section.
Connect an AI client with the LucidLink MCP server
The LucidLink MCP server needs a secret key. Use a collaborator service account scoped to the one filespace or folder the AI client needs. For the install steps, see Installing the LucidLink MCP Server.
If you lose the secret key, create a new one on the same service account. If the client shows no filespaces, the service account probably has no access to one. Check that access was granted to the service account itself.
Troubleshooting
| What you see | Likely cause | What to do |
|---|---|---|
No principal (member or group) was found for given principalId when granting access through the API |
You used a secret key ID instead of the service account ID | Use the service account ID. |
| 403 when a collaborator secret key calls a workspace API endpoint | Collaborator secret keys only authorize file access | Use an admin service account secret key for API calls. |
| A collaborator service account lost access after an update | Collaborator service accounts are no longer in the Everyone group | Grant access directly to the service account. |
| The MCP client lists no filespaces | The collaborator service account has no access | Grant read or write on the filespace or folder. |
| A secret key stopped working | It expired, was deleted, or was single-use and already used | Create a new secret key on the same service account. See Manage service account keys. |
| Key rotation on the command line is rejected | The new secret key belongs to a different service account, or is expired or deleted | Create a new secret key on the linked service account and run rotation again. The daemon keeps its current key. |