Update service account docs

Author: pjlast

docs/admin/access_control/service_accounts.mdx

@@ -1,158 +1,50 @@
-# Service accounts
+# Service Accounts
 
-<TierCallout>
-  Supported on [Enterprise](/pricing/enterprise) plans.
-  <user>
-    Available via the Web app.
-  </user>
-</TierCallout>
+Service accounts are specialized user accounts designed for automation, API integrations, and programmatic access to Sourcegraph, as opposed to using access tokens from regular users. Unlike regular user accounts, service accounts don't require an email address or password and cannot access the Sourcegraph UI. They are specifically intended for automated workflows, CI/CD pipelines, scripts, and other non-human access patterns. Service accounts also don't count towards the user limit and won't be part of any billing cycles.
 
-Service accounts in Sourcegraph are special types of accounts designed for automated tasks and integrations. Unlike regular user accounts, service accounts cannot sign into Sourcegraph directly and can only be used through their associated access tokens.
+## Creating Service Accounts
 
-## What are service accounts?
+Service accounts are created like regular user accounts, but with a few key differences.
 
-Service accounts are non-human accounts that enable:
+- Go to **Site admin** → **Users & auth** → **Users**
+- Click **Create User**
+- Enter a descriptive **Username** (e.g., `ci-automation`, `api-integration`)
+- Check the **Service account** checkbox
+- Click **Create service account**
 
-- **Automated operations**: Run scripts, CI/CD pipelines, or other automated processes that interact with Sourcegraph
-- **API integrations**: Build applications that need to access Sourcegraph programmatically
-- **Secure token management**: Create dedicated tokens for specific purposes without using personal user accounts
+You'll be presented with some next steps you might want to take, like creating an access token, managing and assigning roles, and managing repository permissions.
 
-Key characteristics of service accounts:
+- Service accounts are automatically assigned the "Service Account" system role
+- They appear in the user list with "Service account" type designation
 
-- **Cannot sign in**: Service accounts cannot access the Sourcegraph web interface directly
-- **Token-based access only**: All operations must be performed using access tokens
-- **No user seat usage**: Service accounts don't count toward your user seat limit and won't affect billing
-- **RBAC compatible**: Can be assigned custom roles and permissions like regular users
+## Managing Access Tokens
 
-## Why use service accounts?
+Service accounts authenticate using access tokens rather than passwords. For detailed information about creating, managing, and using access tokens, see:
 
-Service accounts provide several advantages over using personal user accounts for automated tasks:
+- [Creating an access token](/cli/how-tos/creating_an_access_token)
+- [Managing access tokens](/cli/how-tos/managing_access_tokens)
+- [Revoking an access token](/cli/how-tos/revoking_an_access_token)
 
-### Security benefits
-- **Isolated permissions**: Scope access to only what's needed for specific automation tasks
-- **No human login**: Eliminates risk of compromised human credentials affecting automation
-- **Audit trail**: Clearly identify automated vs. human actions in logs and audit trails
+Use service account access tokens to access Sourcegraph's [GraphQL API](/api/graphql).
 
-### Management benefits
-- **Independent lifecycle**: Service accounts persist even if team members leave or change roles
-- **Dedicated purpose**: Each service account can be tailored for specific use cases
-- **No billing impact**: Unlimited service accounts without affecting user seat counts
+## Role-Based Access Control (RBAC)
 
-### Common use cases
-- **CI/CD pipelines**: Automate code analysis, search operations, or batch changes
-- **Monitoring and alerting**: Create dashboards or alerts based on Sourcegraph data
-- **Data integration**: Sync repository data with external systems
-- **Batch operations**: Perform bulk operations across multiple repositories
+Service accounts integrate with Sourcegraph's [role-based access control](/admin/access_control) to provide fine-grained permission control.
 
-## Creating service accounts
+### System Roles
 
-To create a service account:
+Service accounts are automatically assigned the **Service Account** system role, which provides basic API access permissions and standard search capabilities. The **Service Account** system role is applied to all service accounts and can be used to provide service accounts with a default set of permissions. For more specialized service accounts, it is recommended to create custom roles and assign them to service accounts as needed.
 
-1. Navigate to **Site admin > Users & auth > Service accounts**
-2. Click **+ Create service account**
-3. Provide a descriptive name for the service account
-4. Optionally add a description explaining its purpose
-5. Click **Create**
+### Managing Roles
 
-> NOTE: Only site administrators can create and manage service accounts.
+Administrators can assign additional roles to service accounts through the user management interface. For detailed information on managing roles and permissions, see:
 
-## Managing access tokens
+- [Managing roles and permissions](/admin/access_control#managing-roles-and-permissions)
+- [Managing user roles](/admin/access_control#managing-user-roles)
+- [Creating custom roles](/admin/access_control#creating-a-new-role-and-assigning-it-permissions)
 
-Once you've created a service account, you'll need to create access tokens for it to perform operations:
+## Repository Permissions
 
-### Creating access tokens
+Service accounts respect repository permissions and access controls. For comprehensive information about repository permissions, see the [Repository permissions](/admin/permissions) documentation.
 
-1. From the service accounts list, click on the service account you want to create a token for
-2. In the **Access tokens** section, click **+ Generate new token**
-3. Provide a descriptive name for the token
-4. Set an expiration date (recommended for security)
-5. Click **Generate token**
-6. **Important**: Copy the token immediately - it will not be shown again
-
-### Token security best practices
-
-- **Use descriptive names**: Clearly identify what each token is used for
-- **Set expiration dates**: Regularly rotate tokens by setting reasonable expiration periods
-- **Limit scope**: Assign minimal necessary permissions to the service account
-- **Secure storage**: Store tokens securely in your automation systems (environment variables, secret managers)
-- **Monitor usage**: Review access logs to ensure tokens are being used appropriately
-
-## Permissions and role-based access control
-
-Service accounts can be assigned custom roles just like regular users, enabling fine-grained permission control.
-
-### Assigning roles
-
-1. Navigate to **Site admin > Users & auth > Users**
-2. Find the service account in the user list
-3. Click the triple dots to open the context menu
-4. Select **Manage roles**
-5. Assign or remove roles as needed
-6. Click **Update** to save changes
-
-### Permission scoping
-
-Use RBAC to limit service account permissions:
-
-- **Batch Changes**: Control whether the service account can create, modify, or execute batch changes
-- **Repository access**: Combine with [repository permissions](/admin/permissions/) to limit which repositories the service account can access
-- **Custom roles**: Create specific roles tailored to your automation needs
-
-Example role configurations:
-- **CI/CD Service**: Read-only access to repositories, can trigger searches
-- **Batch Change Automation**: Can create and execute batch changes on specific repositories
-- **Monitoring Service**: Read-only access for generating reports and dashboards
-
-## API usage with service accounts
-
-Service accounts work with all Sourcegraph APIs using their access tokens:
-
-### GraphQL API
-```bash
-curl -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>" \
-     -H "Content-Type: application/json" \
-     -d '{"query": "{ currentUser { username } }"}' \
-     https://your-sourcegraph-instance.com/.api/graphql
-```
-
-### REST APIs
-```bash
-curl -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>" \
-     https://your-sourcegraph-instance.com/.api/search/stream?q=test
-```
-
-## Monitoring service account activity
-
-Track service account usage through:
-
-- **Audit logs**: All service account actions are logged with clear identification
-- **Security event logs**: Monitor for unusual access patterns or failures
-- **Access token usage**: Review when tokens were last used and from where
-
-## Troubleshooting
-
-### Common issues
-
-**Service account token not working**
-- Verify the token hasn't expired
-- Check that the service account has the necessary permissions
-- Ensure the token is being passed correctly in API requests
-
-**Permission denied errors**
-- Review the service account's assigned roles
-- Check repository-level permissions if accessing specific repositories
-- Verify the required permissions are included in the service account's roles
-
-**Token generation fails**
-- Ensure you have site administrator privileges
-- Check that the service account exists and is active
-- Verify there are no conflicting token names
-
-## Best practices
-
-1. **Use meaningful names**: Name service accounts and tokens descriptively (e.g., `ci-batch-changes`, `monitoring-dashboard`)
-2. **Regular token rotation**: Set expiration dates and rotate tokens periodically
-3. **Minimal permissions**: Grant only the permissions necessary for each use case
-4. **Monitor and audit**: Regularly review service account activity and permissions
-5. **Document usage**: Keep records of what each service account is used for and by which systems
-6. **Secure token storage**: Never commit tokens to code repositories; use secure secret management
+Service accounts cannot have external service accounts. If service accounts need access to private repositories, they must explicitly be granted access to those repositories. This can be done from the service account's user settings page, under the **Repo permissions** tab, or via [the GraphQL API](/admin/permissions/api#explicit-permissions-api).