Initial service account docs

Author: pjlast

docs/admin/access_control/index.mdx

@@ -42,6 +42,7 @@ You can read about the specific permission types available for each RBAC-enabled
 
 - [Batch Changes](/admin/access_control/batch_changes)
 - [Ownership](/admin/access_control/ownership)
+- [Service accounts](/admin/access_control/service_accounts)
 
 ### Deleting a role
 

docs/admin/access_control/service_accounts.mdx

@@ -0,0 +1,158 @@
+# Service accounts
+
+<TierCallout>
+  Supported on [Enterprise](/pricing/enterprise) plans.
+  <user>
+    Available via the Web app.
+  </user>
+</TierCallout>
+
+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.
+
+## What are service accounts?
+
+Service accounts are non-human accounts that enable:
+
+- **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
+
+Key characteristics of service accounts:
+
+- **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
+
+## Why use service accounts?
+
+Service accounts provide several advantages over using personal user accounts for automated tasks:
+
+### 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
+
+### 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
+
+### 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
+
+## Creating service accounts
+
+To create a service account:
+
+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**
+
+> NOTE: Only site administrators can create and manage service accounts.
+
+## Managing access tokens
+
+Once you've created a service account, you'll need to create access tokens for it to perform operations:
+
+### Creating access tokens
+
+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