1 files changed, 157 insertions, 0 deletions
diff --git a/doc/user/profile/service_accounts.md b/doc/user/profile/service_accounts.md
new file mode 100644
index 00000000000..e593378ce4a
--- /dev/null
+++ b/doc/user/profile/service_accounts.md
@@ -0,0 +1,157 @@
+---
+type: index, howto
+stage: Manage
+group: Authentication and Authorization
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# Service accounts **(PREMIUM ALL)**
+
+A service account is a type of machine user that is not tied to an individual human
+user.
+
+A service account:
+
+- Does not use a licensed seat.
+- Is not a:
+  - Billable user.
+  - Bot user.
+- Is listed in group membership as a service account.
+- Cannot sign into GitLab through the UI.
+
+You should use service accounts in pipelines or integrations where credentials must be
+set up and maintained without being impacted by changes in human user membership.
+
+## Create a service account
+
+The number of service accounts you can create is restricted by the number of service
+accounts allowed under your license:
+
+- On GitLab Free, service accounts are not available.
+- On GitLab Premium, you can create one service account for every paid seat you have.
+- On GitLab Ultimate, you can create an unlimited number of service accounts.
+
+How you create an account differs depending on whether you are on GitLab.com or self-managed.
+
+### GitLab.com
+
+Prerequisite:
+
+- You must have the Owner role in a top-level group.
+
+1. [Create a service account](../../api/groups.md#create-service-account-user).
+
+   This service account is associated only with your top-level group.
+
+1. [Create a personal access token](../../api/groups.md#create-personal-access-token-for-service-account-user)
+   for the service account user.
+
+   You define the scopes for the service account by [setting the scopes for the personal access token](personal_access_tokens.md#personal-access-token-scopes).
+
+   The response includes the personal access token value.
+
+1. Use the returned personal access token value to authenticate with the GitLab API as the service account user.
+
+### Self-managed GitLab
+
+Prerequisite:
+
+- You must be an administrator for your self-managed instance.
+
+1. [Create a service account](../../api/users.md#create-service-account-user).
+
+   This service account is associated with the entire instance, not a specific group
+   or project in the instance.
+
+1. [Create a personal access token](../../api/users.md#create-service-account-user)
+   for the service account user.
+
+   You define the scopes for the service account by [setting the scopes for the personal access token](personal_access_tokens.md#personal-access-token-scopes).
+
+   The response includes the personal access token value.
+
+1. Use the returned personal access token value to authenticate with the GitLab API as the service account user.
+
+## Add a service account to subgroup or project
+
+In terms of functionality, a service account is the same as an [external user](../../administration/external_users.md)
+and has minimal access when you first create it.
+
+You must manually add the service account to each
+[project](../project/members/index.md#add-users-to-a-project) or
+[group](../group/index.md#add-users-to-a-group) you want the account to have access to.
+
+There is no limit to the number of service accounts you can add to a project or group.
+
+A service account:
+
+- Can have different roles across multiple subgroups and projects of the same top level group.
+- On GitLab.com, only belongs to one top-level group.
+
+### Add to a subgroup
+
+You can add the service account to a subgroup [through the UI](../group/index.md#add-users-to-a-group)
+or API.
+
+To add the service account through the API, call the following endpoint:
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <ACCESS TOKEN>" --data "user_id=<service_account_user_id>&access_level=30" "https://gitlab.example.com/api/v4/groups/<subgroup_id>/members"
+```
+
+### Add to a project
+
+You can add the service account to a project [through the UI](../project/members/index.md#add-users-to-a-project)
+or API.
+
+To add the service account through the API, call the following endpoint:
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <PRIVATE-TOKEN>" --data "user_id=<service_account_user_id>&access_level=30" "https://gitlab.example.com/api/v4/projects/<project_id>/members"
+```
+
+### Change a service account role in a subgroup or project
+
+You can change a service account role in a subgroup or project through the UI or the API.
+
+To use the UI, go to the subgroup's or project's membership list and change the service
+account's role.
+
+To use the API, call the following endpoint:
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <PRIVATE-TOKEN>" \ --data "user_id=<service_account_user_id>&access_level=30" "https://gitlab.example.com/api/v4/projects/<project_id>/members"
+```
+
+For more information on the attributes, see the [API documentation on editing a member of a group or project](../../api/members.md#edit-a-member-of-a-group-or-project).
+
+### Rotate the personal access token
+
+Prerequisites:
+
+- For GitLab.com, you must have the Owner role in a top-level group.
+- For self-managed GitLab, you must be an administrator for your self-managed instance.
+
+Use the groups API to [rotate the personal access token](../../api/groups.md#rotate-a-personal-access-token-for-service-account-user) for a service account user.
+
+### Disable a service account
+
+You cannot directly disable or delete a service account. Instead, you must:
+
+1. Remove the service account as a member of all subgroups and projects:
+
+   ```shell
+   curl --request DELETE --header "PRIVATE-TOKEN: <access_token_id>" "https://gitlab.example.com/api/v4/groups/<group_id>/members/<service_account_id>"
+   ```
+
+   For more information, see the [API documentation on removing a member from a group or project](../../api/members.md#remove-a-member-from-a-group-or-project).
+
+1. Revoke the personal access token using the [UI](personal_access_tokens.md#revoke-a-personal-access-token) or the [API](../../api/personal_access_tokens.md#revoke-a-personal-access-token).
+
+## Related topics
+
+- [Billable users](../../subscriptions/self_managed/index.md#billable-users)
+- [Associated records](account/delete_account.md#associated-records)
+- [Project access tokens - bot users](../project/settings/project_access_tokens.md#bot-users-for-projects)
+- [Group access tokens - bot users](../group/settings/group_access_tokens.md#bot-users-for-groups)
+- [Internal users](../../development/internal_users.md#internal-users)