Document explicit permissions in the Sourcegraph API

cspell-allow-list.txt

@@ -200,6 +200,7 @@ etcdctl
 euxo
 EVICTEDPOD
 exfiltration
+explicitrepopermissions
 explorable
 externalapi
 extsvc

docs/admin/config/authorization-and-authentication.mdx

@@ -154,7 +154,7 @@ The final and complete `auth.providers` configuration may look like this:
 
 ### Explicit Permissions API authorization
 
-With any authentication mechanism, you can use our GraphQL API to set permissions for all repositories. If you choose to do this, this is the _only_ mechanism that can be used for permissions—all others will be ignored. Follow the instructions for the [mutations needed within the GraphQL API](/admin/permissions/api) to configure access.
+With any authentication mechanism, you can use the [Sourcegraph API](/api) to explicitly grant users access to repositories. Explicit permissions can be used alongside permissions synced from code hosts; see [permissions mechanisms in parallel](/admin/permissions/#permissions-mechanisms-in-parallel). Follow the instructions in the [explicit permissions API documentation](/admin/permissions/api) to configure access.
 
 ### OpenID Connect authentication
 

docs/admin/permissions/api.mdx

@@ -1,6 +1,6 @@
 # Explicit permissions API
 
-Sourcegraph's GraphQL API allows users to explicitly set repository permissions. This is an alternative to other mechanisms, which involve directly talking to the code host.
+The [Sourcegraph API](/api) allows users to explicitly set repository permissions. This is an alternative to other mechanisms, which involve directly talking to the code host.
 
 ## Permissions mechanisms in parallel
 
@@ -42,6 +42,22 @@ After you enable the permissions API, you must [set permissions](#setting-reposi
 
 > NOTE: In some cases, in order for the repo permissions to be enforced, you must re-save the code host connection configuration with some modification to the JSON after enabling the permissions API.
 
+## Managing explicit permissions
+
+Use the `explicitrepopermissions.v1.Service` operations to grant, revoke, check, and list explicit permissions. See `/api-reference` on your Sourcegraph instance (e.g. `https://sourcegraph.example.com/api-reference`) for the operations, request examples, and schemas. Requests need an [access token](/cli/how-tos/creating-an-access-token) with the `externalapi:read` scope to read and `externalapi:write` to make changes, for a user with the `REPO_PERMISSIONS` [permission](/admin/access-control) (administrators have it by default).
+
+The Sourcegraph API identifies repositories by numeric ID and cannot look them up by name yet. Get the ID with the [GraphQL API](/api/graphql):
+
+```graphql
+query {
+	repository(name: "github.example.com/owner/repo") {
+		databaseID
+	}
+}
+```
+
+The following operations are only available in the [GraphQL API](/api/graphql) for now.
+
 ## Setting a repository as unrestricted
 
 Sometimes it can be useful to mark a repository as `unrestricted`, meaning that it is available to all Sourcegraph users. This can be done with the `setRepositoryPermissionsUnrestricted` mutation. Marking a repository as unrestricted will disregard any previously set explicit or synced permissions. Setting `unrestricted` back to `false` will restore the previous behaviour.
@@ -88,6 +104,8 @@ Now, only the users specified in the `userPermissions` parameter will be allowed
 
 You can call `setRepositoryPermissionsForUsers` repeatedly to set permissions for each repository, and whenever you want to change the list of authorized users.
 
+> NOTE: The mutation also removes permissions granted with the Sourcegraph API.
+
 ## Setting sub-repository permissions for users
 
 > NOTE: If a user has no sub-repo permissions set for a specific repository (assuming that they have general access to the repository), they will have access to the entire repository contents.

docs/admin/service-accounts.mdx

@@ -119,6 +119,6 @@ Administrators can assign additional roles to service accounts through the user
 
 Service accounts respect repository permissions and access controls. For comprehensive information about repository permissions, see the [Repository permissions](/admin/permissions) documentation.
 
-Service accounts by default can only access public and unrestricted repositories in Sourcegraph. You may explicitly grant fine-grained access to private repositories from the service account's user settings page, under the **Repo permissions** tab, or via [the GraphQL API](/admin/permissions/api#explicit-permissions-api). In the **Repo permissions** tab, you can also grant service accounts access to all current and future repositories on Sourcegraph, regardless of their visibility, which is useful for service accounts that need to do things like perform search jobs, but admins should take care to ensure that the access tokens for these accounts are not shared with unauthorized users.
+Service accounts by default can only access public and unrestricted repositories in Sourcegraph. You may explicitly grant fine-grained access to private repositories from the service account's user settings page, under the **Repo permissions** tab, or via the [explicit permissions API](/admin/permissions/api#managing-explicit-permissions). In the **Repo permissions** tab, you can also grant service accounts access to all current and future repositories on Sourcegraph, regardless of their visibility, which is useful for service accounts that need to do things like perform search jobs, but admins should take care to ensure that the access tokens for these accounts are not shared with unauthorized users.
 
 ![service-account-repo-permissions](https://storage.googleapis.com/sourcegraph-assets/Docs/service-accounts-repo-permissions-0625.png)