Service accounts are for machine-to-machine access. For your own interactive or personal automation, use a personal API token instead — see User Settings.
When to use a service account
- The credential should belong to a team or system, not an individual, so it keeps working when people join or leave.
- You want access scoped to specific workspaces and roles, independent of any person’s permissions.
- You need several tokens for the same identity (for example, one per environment) that you can rotate independently.
Creating a service account
- Go to Org Admin > Service Accounts.
- Click + New service account.
- Enter a Name. This becomes a permanent identifier of the form
name@<org>.svc.delphina.ai. Use lowercase letters, digits, and hyphens (not at the start or end), up to 64 characters. - Optionally add a Description explaining what the account is used for.
- Click Create.
Assigning workspace roles
A service account can only act in workspaces you assign to it. In the account’s management dialog, open the Workspace roles tab.- Select a Workspace and a Role, then click Add.
- Repeat for each workspace the account needs.
Home workspace
The home workspace is the workspace the account defaults to when it authenticates. Set it from the Workspace roles tab once at least one role is assigned. It must be one of the account’s assigned workspaces.Managing tokens
Open the Tokens tab in the account’s management dialog.Create a token
- Click + Create token.
- Optionally give the token a Name to identify where it’s used.
- Choose an expiration: No expiration, or 7 / 30 / 90 / 180 / 365 days.
- Click Create token.
Authorization: Bearer … header. Copy it now — for security, the token is never shown again. Afterward the list displays only a masked form (prefix + last four characters).
Token list
Each token row shows its name, masked value, created date, last used date, and expiration. Use this to spot unused or soon-to-expire tokens.Revoke a token
Click the trash icon on a token row and confirm. Revocation takes effect immediately and cannot be undone — any integration using that token stops working. Revoked tokens are hidden by default; toggle Show revoked to see them (kept for the audit trail).Using a token
Send the token as a bearer credential on your API requests:Deleting a service account
Click the trash icon on a service account row (or Delete service account in its management dialog) and confirm. Deleting an account revokes all of its tokens immediately and cannot be undone. Any integration using them stops working.Security best practices
- Give each integration its own token so you can revoke one without disrupting the others.
- Scope service accounts to the fewest workspaces and the lowest role they need.
- Set an expiration on tokens where practical, and rotate long-lived tokens periodically.
- Never commit tokens to source control. Store them in a secrets manager or environment variables.
- Revoke a token as soon as it’s no longer needed or may have been exposed.