From 2affc975f6e5079afe63107bf14c9d7b6d7abe7d Mon Sep 17 00:00:00 2001 From: Taras Yemets Date: Fri, 9 Oct 2026 11:56:06 +0000 Subject: [PATCH 1/8] Document explicit permissions in the Sourcegraph API The explicit permissions page only described the GraphQL API, even though Sourcegraph 7.4 added explicit repository permissions to the Sourcegraph API (explicitrepopermissions.v1.Service). --- .../authorization-and-authentication.mdx | 2 +- docs/admin/permissions/api.mdx | 179 ++++++++++++++++-- docs/admin/service-accounts.mdx | 2 +- 3 files changed, 162 insertions(+), 21 deletions(-) diff --git a/docs/admin/config/authorization-and-authentication.mdx b/docs/admin/config/authorization-and-authentication.mdx index 84eadcd01..62c2ebce4 100644 --- a/docs/admin/config/authorization-and-authentication.mdx +++ b/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 diff --git a/docs/admin/permissions/api.mdx b/docs/admin/permissions/api.mdx index a3040c10e..f0c402a39 100644 --- a/docs/admin/permissions/api.mdx +++ b/docs/admin/permissions/api.mdx @@ -1,6 +1,8 @@ # 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 you to explicitly grant and revoke individual users' access to repositories. This is an alternative to other mechanisms, which involve directly talking to the code host. + +Explicit permissions are available in the Sourcegraph API starting in Sourcegraph 7.4. A few capabilities, such as marking a repository as unrestricted and sub-repository permissions, are still only available through the [Sourcegraph GraphQL debug API](/api/graphql). See [Capabilities only available in the GraphQL API](#capabilities-only-available-in-the-graphql-api). ## Permissions mechanisms in parallel @@ -31,47 +33,171 @@ To enable the permissions API, add the following to the [advanced configuration] } ``` -The `bindID` value specifies how to uniquely identify users when setting permissions: +The `bindID` value specifies how to uniquely identify users when setting permissions with the [GraphQL operations](#capabilities-only-available-in-the-graphql-api). The Sourcegraph API does not use `bindID`; it identifies users by [resource name](#resource-names) instead. - `username`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their Sourcegraph usernames. Using usernames is **preferred**, as usernames are required to be unique for each user. - `email`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their email addresses (which must be verified primary emails associated with their Sourcegraph user account). This method can lead to unexpected results if there are multiple Sourcegraph user accounts with the same verified email address. Also, the email address is case-sensitive, so it should be exactly the same as set on the sourcegraph UI. -After you enable the permissions API, you must [set permissions](#setting-repository-permissions-for-users) to allow users to view repositories (administrators bypass all permissions checks and can always view all repositories). +After you enable the permissions API, you must [grant permissions](#managing-explicit-permissions) to allow users to view repositories (administrators bypass all permissions checks and can always view all repositories). > NOTE: If you were previously using [permissions syncing](/admin/permissions/syncing), e.g. syncing permissions from Github, then those permissions are used as the initial state after enabling explicit permissions. Otherwise, the initial state is for all repositories to have an empty set of authorized users, so users will not be able to view any repositories. > 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. -## Setting a repository as unrestricted +## Authentication and authorization -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. +Requests to the Sourcegraph API must use a token; browser sessions are not accepted. Use one of the following: -For example: +- An [access token](/cli/how-tos/creating-an-access-token), in the `Authorization: token ` header. +- An M2M token for a [service account](/admin/service-accounts) or a token issued by an [OAuth app](/admin/oauth-apps), in the `Authorization: Bearer ` header. + +The token needs the following scopes: + +| Operations | Required scope | +| -------------------------------------------------------------- | ------------------- | +| `GetExplicitRepoPermission`, `ListExplicitRepoPermissions` | `externalapi:read` | +| `CreateExplicitRepoPermission`, `DeleteExplicitRepoPermission` | `externalapi:write` | + +Tokens with the `user:all` scope are also accepted, but their use is recorded in the audit log. We recommend creating tokens with the `externalapi:*` scopes for integrations. + +The user the token belongs to must also have the `REPO_PERMISSIONS#READ` permission for read operations and `REPO_PERMISSIONS#WRITE` for write operations. The Administrator [role](/admin/access-control) has both by default. + +The explicit permissions API also requires a license that includes the explicit permissions API feature. Without it, requests fail with a `failed_precondition` error. + +## Managing explicit permissions + +Each operation is served at `https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/` and accepts a JSON request body with `POST`. The full schema, including request and response types, is available at `/api-reference` on your instance (for example, `https://sourcegraph.example.com/api-reference`). + +| Operation | Description | +| ------------------------------ | --------------------------------------------------------- | +| `CreateExplicitRepoPermission` | Grant a user explicit access to a repository. | +| `DeleteExplicitRepoPermission` | Revoke a user's explicit access to a repository. | +| `GetExplicitRepoPermission` | Check whether a user has explicit access to a repository. | +| `ListExplicitRepoPermissions` | List explicit permissions for a repository or for a user. | + +Each permission is a single grant for one user on one repository. Granting or revoking access for one user does not change the access of any other user. + +### Resource names + +Resources are identified by resource names: + +- **Repository**: `repositories/`, where the repository ID is numeric, for example `repositories/123`. See [Finding a repository's ID](#finding-a-repositorys-id). +- **User**: `users/`, `users/@`, or `users/`, for example `users/456`, `users/@alice`, or `users/alice@example.com`. +- **Permission**: `repositories//explicitRepoPermissions/`, where `` accepts the same formats as a user resource name without the `users/` prefix, for example `repositories/123/explicitRepoPermissions/@alice`. + +Responses always identify repositories and users by their numeric IDs. + +### Finding a repository's ID + +The Sourcegraph API does not yet support looking up a repository by name. You can get the numeric repository ID from the [GraphQL debug API](/api/graphql): ```graphql -mutation { - setRepositoryPermissionsUnrestricted( - repositories: ["", "", ""] - unrestricted: true - ) +query { + repository(name: "github.example.com/owner/repo") { + databaseID + } +} +``` + +### Granting a user access to a repository + +The following example grants the user `alice` access to the repository with ID `123`. The other examples on this page use the same `SRC_ACCESS_TOKEN`. + +```bash +export SRC_ACCESS_TOKEN="sgp_example" + +curl -X POST "https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/CreateExplicitRepoPermission" \ + -H "Authorization: token $SRC_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "parent": "repositories/123", + "explicitRepoPermission": { "user": "users/@alice" } + }' +``` + +The response contains the created permission: + +```json +{ + "name": "repositories/123/explicitRepoPermissions/456", + "user": "users/456", + "repository": "repositories/123" +} +``` + +You can also use the user as the parent and specify the repository instead, for example `{"parent": "users/@alice", "explicitRepoPermission": {"repository": "repositories/123"}}`. + +If the user already has explicit access to the repository, the request fails with an `already_exists` error. The user must already exist in Sourcegraph; otherwise the request fails with a `not_found` error. + +### Listing explicit permissions + +To list every user with explicit access to a repository, use the repository as the parent: + +```bash +curl -X POST "https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/ListExplicitRepoPermissions" \ + -H "Authorization: token $SRC_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ "parent": "repositories/123", "pageSize": 100 }' +``` + +To list every repository a user has explicit access to, use the user as the parent, for example `{"parent": "users/@alice"}`. + +```json +{ + "explicitRepoPermissions": [ + { + "name": "repositories/123/explicitRepoPermissions/456", + "user": "users/456", + "repository": "repositories/123" + } + ], + "nextPageToken": "..." } ``` -## Setting repository permissions for users +To get the next page, repeat the request with `pageToken` set to the returned `nextPageToken`. When `nextPageToken` is empty or missing, there are no more results. + +The list only contains permissions granted through the explicit permissions API. Permissions synced from code hosts are not included. To see all repositories a user can access, see [Listing a user's authorized repositories](#listing-a-users-authorized-repositories). + +### Checking a single permission + +```bash +curl -X POST "https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/GetExplicitRepoPermission" \ + -H "Authorization: token $SRC_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ "name": "repositories/123/explicitRepoPermissions/@alice" }' +``` + +If the user does not have explicit access to the repository, the request fails with a `not_found` error. + +### Revoking a user's access to a repository + +```bash +curl -X POST "https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/DeleteExplicitRepoPermission" \ + -H "Authorization: token $SRC_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ "name": "repositories/123/explicitRepoPermissions/@alice" }' +``` + +A successful request returns an empty JSON object. Only permissions granted through the explicit permissions API can be revoked; for a permission synced from a code host, or one that does not exist, the request fails with a `not_found` error. + +## Capabilities only available in the GraphQL API -Setting the permissions for a user can be accomplished with 2 [GraphQL API](/api/graphql) calls. +The following capabilities are not yet available in the Sourcegraph API. Use the [Sourcegraph GraphQL debug API](/api/graphql) for them. The GraphQL API does not provide compatibility guarantees, so prefer the Sourcegraph API for everything it supports. -First, obtain the ID of the repository from its name: +GraphQL operations identify repositories by their GraphQL ID, which you can get with the following query: ```graphql query { - repository(name: "github.com/owner/repo") { + repository(name: "github.example.com/owner/repo") { id } } ``` -Next, set the list of users allowed to view the repository: +### Setting repository permissions for users + +The `setRepositoryPermissionsForUsers` mutation replaces the full list of users allowed to view a repository in one call. Users are identified by their `bindID`, and permissions for a `bindID` that does not match an existing user are applied when that user is created. ```graphql mutation { @@ -84,11 +210,26 @@ mutation { } ``` -Now, only the users specified in the `userPermissions` parameter will be allowed to view the repository. Sourcegraph automatically enforces these permissions for all operations. (Administrators bypass all permissions checks by default. See the [Administrators](/admin/permissions/#site-administrators) section) +Now, only the users specified in the `userPermissions` parameter will be allowed to view the repository. Sourcegraph automatically enforces these permissions for all operations. (Administrators bypass all permissions checks by default. See the [Administrators](/admin/permissions/#administrators) section) + +> NOTE: The mutation replaces all explicit permissions for the repository, including permissions granted with the Sourcegraph API. + +### 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. + +For example: -You can call `setRepositoryPermissionsForUsers` repeatedly to set permissions for each repository, and whenever you want to change the list of authorized users. +```graphql +mutation { + setRepositoryPermissionsUnrestricted( + repositories: ["", "", ""] + unrestricted: true + ) +} +``` -## Setting sub-repository permissions for users +### 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. diff --git a/docs/admin/service-accounts.mdx b/docs/admin/service-accounts.mdx index 5c8f73fd9..2342a9a2e 100644 --- a/docs/admin/service-accounts.mdx +++ b/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) From 2aa73c99281da61c28edbaedba049800f24dd2b5 Mon Sep 17 00:00:00 2001 From: Taras Yemets Date: Fri, 9 Oct 2026 11:58:03 +0000 Subject: [PATCH 2/8] Explain how to sync a repository's explicit permissions with the Sourcegraph API --- docs/admin/permissions/api.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin/permissions/api.mdx b/docs/admin/permissions/api.mdx index f0c402a39..f267c2cb1 100644 --- a/docs/admin/permissions/api.mdx +++ b/docs/admin/permissions/api.mdx @@ -75,7 +75,7 @@ Each operation is served at `https://sourcegraph.example.com/api/explicitrepoper | `GetExplicitRepoPermission` | Check whether a user has explicit access to a repository. | | `ListExplicitRepoPermissions` | List explicit permissions for a repository or for a user. | -Each permission is a single grant for one user on one repository. Granting or revoking access for one user does not change the access of any other user. +Each permission is a single grant for one user on one repository. Granting or revoking access for one user does not change the access of any other user. To make a repository's explicit permissions match a list of users, [list](#listing-explicit-permissions) the repository's current permissions, [grant](#granting-a-user-access-to-a-repository) access to users missing from the list, and [revoke](#revoking-a-users-access-to-a-repository) access from users not in the list. ### Resource names @@ -197,7 +197,7 @@ query { ### Setting repository permissions for users -The `setRepositoryPermissionsForUsers` mutation replaces the full list of users allowed to view a repository in one call. Users are identified by their `bindID`, and permissions for a `bindID` that does not match an existing user are applied when that user is created. +The `setRepositoryPermissionsForUsers` mutation replaces the full list of users allowed to view a repository in one call. Use it if you need to grant access to users who do not exist in Sourcegraph yet: users are identified by their `bindID`, and permissions for a `bindID` that does not match an existing user are applied when that user is created. ```graphql mutation { From f45207e5fe8f5a4db3b21474de64847ad65b2d7a Mon Sep 17 00:00:00 2001 From: Taras Yemets Date: Fri, 9 Oct 2026 13:30:34 +0000 Subject: [PATCH 3/8] Correct explicit permissions details found while testing against a devserver --- docs/admin/permissions/api.mdx | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/admin/permissions/api.mdx b/docs/admin/permissions/api.mdx index f267c2cb1..1fdc1e017 100644 --- a/docs/admin/permissions/api.mdx +++ b/docs/admin/permissions/api.mdx @@ -24,7 +24,7 @@ Keeping the permissions in sync and fresh is the responsibility of the administr ## Configuration -To enable the permissions API, add the following to the [advanced configuration](/admin/config/site-config): +The Sourcegraph API operations work without this setting. To restrict repositories from code host connections that don't sync permissions, so that only users with explicit permissions can view them, add the following to the [advanced configuration](/admin/config/site-config): ```json "permissions.userMapping": { @@ -36,11 +36,11 @@ To enable the permissions API, add the following to the [advanced configuration] The `bindID` value specifies how to uniquely identify users when setting permissions with the [GraphQL operations](#capabilities-only-available-in-the-graphql-api). The Sourcegraph API does not use `bindID`; it identifies users by [resource name](#resource-names) instead. - `username`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their Sourcegraph usernames. Using usernames is **preferred**, as usernames are required to be unique for each user. -- `email`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their email addresses (which must be verified primary emails associated with their Sourcegraph user account). This method can lead to unexpected results if there are multiple Sourcegraph user accounts with the same verified email address. Also, the email address is case-sensitive, so it should be exactly the same as set on the sourcegraph UI. +- `email`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their email addresses (which must be verified emails associated with their Sourcegraph user account). This method can lead to unexpected results if there are multiple Sourcegraph user accounts with the same verified email address. Also, the email address is case-sensitive, so it should be exactly the same as set on the sourcegraph UI. -After you enable the permissions API, you must [grant permissions](#managing-explicit-permissions) to allow users to view repositories (administrators bypass all permissions checks and can always view all repositories). +After you enable this setting, you must [grant permissions](#managing-explicit-permissions) to allow users to view private repositories. Public repositories remain visible to all users, and administrators bypass all permissions checks by default. -> NOTE: If you were previously using [permissions syncing](/admin/permissions/syncing), e.g. syncing permissions from Github, then those permissions are used as the initial state after enabling explicit permissions. Otherwise, the initial state is for all repositories to have an empty set of authorized users, so users will not be able to view any repositories. +> NOTE: If you were previously using [permissions syncing](/admin/permissions/syncing), e.g. syncing permissions from Github, then those permissions are used as the initial state after enabling explicit permissions. Otherwise, the initial state is for all private repositories to have an empty set of authorized users, so users will not be able to view them. > 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. @@ -58,7 +58,7 @@ The token needs the following scopes: | `GetExplicitRepoPermission`, `ListExplicitRepoPermissions` | `externalapi:read` | | `CreateExplicitRepoPermission`, `DeleteExplicitRepoPermission` | `externalapi:write` | -Tokens with the `user:all` scope are also accepted, but their use is recorded in the audit log. We recommend creating tokens with the `externalapi:*` scopes for integrations. +Tokens with the `user:all` scope are also accepted. Requests that rely on `user:all` instead of an `externalapi:*` scope are recorded in the audit log. We recommend creating tokens with the `externalapi:*` scopes for integrations. The user the token belongs to must also have the `REPO_PERMISSIONS#READ` permission for read operations and `REPO_PERMISSIONS#WRITE` for write operations. The Administrator [role](/admin/access-control) has both by default. @@ -75,7 +75,7 @@ Each operation is served at `https://sourcegraph.example.com/api/explicitrepoper | `GetExplicitRepoPermission` | Check whether a user has explicit access to a repository. | | `ListExplicitRepoPermissions` | List explicit permissions for a repository or for a user. | -Each permission is a single grant for one user on one repository. Granting or revoking access for one user does not change the access of any other user. To make a repository's explicit permissions match a list of users, [list](#listing-explicit-permissions) the repository's current permissions, [grant](#granting-a-user-access-to-a-repository) access to users missing from the list, and [revoke](#revoking-a-users-access-to-a-repository) access from users not in the list. +Each permission is a single grant for one user on one repository. Granting or revoking access for one user does not change the access of any other user. To make a repository's explicit permissions match a list of users, [list](#listing-explicit-permissions) the repository's current permissions, [grant](#granting-a-user-access-to-a-repository) access to users missing from the list, and [revoke](#revoking-a-users-access-to-a-repository) access from users not in the list. Unlike the GraphQL [`setRepositoryPermissionsForUsers`](#setting-repository-permissions-for-users) mutation, this is not a single atomic change, and it only works for users who already exist in Sourcegraph. ### Resource names @@ -157,7 +157,7 @@ To list every repository a user has explicit access to, use the user as the pare To get the next page, repeat the request with `pageToken` set to the returned `nextPageToken`. When `nextPageToken` is empty or missing, there are no more results. -The list only contains permissions granted through the explicit permissions API. Permissions synced from code hosts are not included. To see all repositories a user can access, see [Listing a user's authorized repositories](#listing-a-users-authorized-repositories). +The list only contains explicit permissions, including those granted to existing users with the GraphQL API. Permissions synced from code hosts, and [pending permissions](#setting-repository-permissions-for-users) that were later applied to a user, are not included. To list a user's stored permissions from all sources, see [Listing a user's authorized repositories](#listing-a-users-authorized-repositories). ### Checking a single permission @@ -179,7 +179,7 @@ curl -X POST "https://sourcegraph.example.com/api/explicitrepopermissions.v1.Ser -d '{ "name": "repositories/123/explicitRepoPermissions/@alice" }' ``` -A successful request returns an empty JSON object. Only permissions granted through the explicit permissions API can be revoked; for a permission synced from a code host, or one that does not exist, the request fails with a `not_found` error. +A successful request returns an empty JSON object. Only explicit permissions can be revoked: if the user only has access through permissions synced from a code host, or has no access, the request fails with a `not_found` error. Revoking an explicit permission does not remove access the user has through synced permissions. ## Capabilities only available in the GraphQL API @@ -197,7 +197,7 @@ query { ### Setting repository permissions for users -The `setRepositoryPermissionsForUsers` mutation replaces the full list of users allowed to view a repository in one call. Use it if you need to grant access to users who do not exist in Sourcegraph yet: users are identified by their `bindID`, and permissions for a `bindID` that does not match an existing user are applied when that user is created. +The `setRepositoryPermissionsForUsers` mutation replaces a repository's explicit permissions with a new list of users in one call. Use it if you need to grant access to users who do not exist in Sourcegraph yet: users are identified by their `bindID`, and permissions for a `bindID` that does not match an existing user are stored as pending. Pending permissions for a username are applied when a matching user is created; pending permissions for an email address are applied when a user verifies that address. ```graphql mutation { @@ -210,9 +210,9 @@ mutation { } ``` -Now, only the users specified in the `userPermissions` parameter will be allowed to view the repository. Sourcegraph automatically enforces these permissions for all operations. (Administrators bypass all permissions checks by default. See the [Administrators](/admin/permissions/#administrators) section) +Now, only the users specified in the `userPermissions` parameter have explicit permissions for the repository. Other users can still view it if they have access through permissions synced from a code host, or if the repository is public. Sourcegraph automatically enforces these permissions for all operations. (Administrators bypass all permissions checks by default. See the [Administrators](/admin/permissions/#administrators) section) -> NOTE: The mutation replaces all explicit permissions for the repository, including permissions granted with the Sourcegraph API. +> NOTE: The mutation replaces all explicit permissions and pending permissions for the repository, including permissions granted with the Sourcegraph API. It also removes the repository's [unrestricted](#setting-a-repository-as-unrestricted) setting. ### Setting a repository as unrestricted @@ -225,7 +225,9 @@ mutation { setRepositoryPermissionsUnrestricted( repositories: ["", "", ""] unrestricted: true - ) + ) { + alwaysNil + } } ``` @@ -275,7 +277,7 @@ The default permission if a path is not specified is to deny access. ### Listing a user's authorized repositories -You may query the set of repositories visible to a particular user with the `authorizedUserRepositories` [GraphQL API](/api/graphql) query, which accepts a `username` or `email` parameter to specify the user: +You may query the repositories a particular user has stored permissions for, from explicit permissions and from code host syncing, with the `authorizedUserRepositories` [GraphQL API](/api/graphql) query. It accepts a `username` or `email` parameter to specify the user, and returns pending permissions for users who do not exist yet. It does not include repositories the user can view only because they are public or unrestricted. ```graphql query { From 5b1a24ee0350c05900aee795ef5d555395ef6686 Mon Sep 17 00:00:00 2001 From: Taras Yemets Date: Fri, 9 Oct 2026 14:15:59 +0000 Subject: [PATCH 4/8] Trim the explicit permissions page to a minimal switch to the Sourcegraph API --- cspell-allow-list.txt | 1 + docs/admin/permissions/api.mdx | 180 +++++++-------------------------- 2 files changed, 36 insertions(+), 145 deletions(-) diff --git a/cspell-allow-list.txt b/cspell-allow-list.txt index 4fdce36b5..d71ae4878 100644 --- a/cspell-allow-list.txt +++ b/cspell-allow-list.txt @@ -200,6 +200,7 @@ etcdctl euxo EVICTEDPOD exfiltration +explicitrepopermissions explorable externalapi extsvc diff --git a/docs/admin/permissions/api.mdx b/docs/admin/permissions/api.mdx index 1fdc1e017..1f5ca73e6 100644 --- a/docs/admin/permissions/api.mdx +++ b/docs/admin/permissions/api.mdx @@ -1,8 +1,6 @@ # Explicit permissions API -The [Sourcegraph API](/api) allows you to explicitly grant and revoke individual users' access to repositories. This is an alternative to other mechanisms, which involve directly talking to the code host. - -Explicit permissions are available in the Sourcegraph API starting in Sourcegraph 7.4. A few capabilities, such as marking a repository as unrestricted and sub-repository permissions, are still only available through the [Sourcegraph GraphQL debug API](/api/graphql). See [Capabilities only available in the GraphQL API](#capabilities-only-available-in-the-graphql-api). +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 @@ -24,7 +22,7 @@ Keeping the permissions in sync and fresh is the responsibility of the administr ## Configuration -The Sourcegraph API operations work without this setting. To restrict repositories from code host connections that don't sync permissions, so that only users with explicit permissions can view them, add the following to the [advanced configuration](/admin/config/site-config): +To enable the permissions API, add the following to the [advanced configuration](/admin/config/site-config): ```json "permissions.userMapping": { @@ -33,40 +31,24 @@ The Sourcegraph API operations work without this setting. To restrict repositori } ``` -The `bindID` value specifies how to uniquely identify users when setting permissions with the [GraphQL operations](#capabilities-only-available-in-the-graphql-api). The Sourcegraph API does not use `bindID`; it identifies users by [resource name](#resource-names) instead. +The `bindID` value specifies how to uniquely identify users when setting permissions: - `username`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their Sourcegraph usernames. Using usernames is **preferred**, as usernames are required to be unique for each user. -- `email`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their email addresses (which must be verified emails associated with their Sourcegraph user account). This method can lead to unexpected results if there are multiple Sourcegraph user accounts with the same verified email address. Also, the email address is case-sensitive, so it should be exactly the same as set on the sourcegraph UI. - -After you enable this setting, you must [grant permissions](#managing-explicit-permissions) to allow users to view private repositories. Public repositories remain visible to all users, and administrators bypass all permissions checks by default. - -> NOTE: If you were previously using [permissions syncing](/admin/permissions/syncing), e.g. syncing permissions from Github, then those permissions are used as the initial state after enabling explicit permissions. Otherwise, the initial state is for all private repositories to have an empty set of authorized users, so users will not be able to view them. - -> 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. - -## Authentication and authorization - -Requests to the Sourcegraph API must use a token; browser sessions are not accepted. Use one of the following: - -- An [access token](/cli/how-tos/creating-an-access-token), in the `Authorization: token ` header. -- An M2M token for a [service account](/admin/service-accounts) or a token issued by an [OAuth app](/admin/oauth-apps), in the `Authorization: Bearer ` header. - -The token needs the following scopes: +- `email`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their email addresses (which must be verified primary emails associated with their Sourcegraph user account). This method can lead to unexpected results if there are multiple Sourcegraph user accounts with the same verified email address. Also, the email address is case-sensitive, so it should be exactly the same as set on the sourcegraph UI. -| Operations | Required scope | -| -------------------------------------------------------------- | ------------------- | -| `GetExplicitRepoPermission`, `ListExplicitRepoPermissions` | `externalapi:read` | -| `CreateExplicitRepoPermission`, `DeleteExplicitRepoPermission` | `externalapi:write` | +`bindID` applies to the GraphQL operations; the Sourcegraph API identifies users as `users/@`, `users/`, or `users/`. -Tokens with the `user:all` scope are also accepted. Requests that rely on `user:all` instead of an `externalapi:*` scope are recorded in the audit log. We recommend creating tokens with the `externalapi:*` scopes for integrations. +After you enable the permissions API, you must [set permissions](#setting-repository-permissions-for-users) to allow users to view repositories (administrators bypass all permissions checks and can always view all repositories). -The user the token belongs to must also have the `REPO_PERMISSIONS#READ` permission for read operations and `REPO_PERMISSIONS#WRITE` for write operations. The Administrator [role](/admin/access-control) has both by default. +> NOTE: If you were previously using [permissions syncing](/admin/permissions/syncing), e.g. syncing permissions from Github, then those permissions are used as the initial state after enabling explicit permissions. Otherwise, the initial state is for all repositories to have an empty set of authorized users, so users will not be able to view any repositories. -The explicit permissions API also requires a license that includes the explicit permissions API feature. Without it, requests fail with a `failed_precondition` error. +> 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 -Each operation is served at `https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/` and accepts a JSON request body with `POST`. The full schema, including request and response types, is available at `/api-reference` on your instance (for example, `https://sourcegraph.example.com/api-reference`). +The Sourcegraph API requires an [access token](/cli/how-tos/creating-an-access-token) with the `externalapi:read` scope for read operations or the `externalapi:write` scope for write operations, for a user with the `REPO_PERMISSIONS` permission (administrators have it by default). + +Each operation is served at `/api/explicitrepopermissions.v1.Service/`: | Operation | Description | | ------------------------------ | --------------------------------------------------------- | @@ -75,21 +57,7 @@ Each operation is served at `https://sourcegraph.example.com/api/explicitrepoper | `GetExplicitRepoPermission` | Check whether a user has explicit access to a repository. | | `ListExplicitRepoPermissions` | List explicit permissions for a repository or for a user. | -Each permission is a single grant for one user on one repository. Granting or revoking access for one user does not change the access of any other user. To make a repository's explicit permissions match a list of users, [list](#listing-explicit-permissions) the repository's current permissions, [grant](#granting-a-user-access-to-a-repository) access to users missing from the list, and [revoke](#revoking-a-users-access-to-a-repository) access from users not in the list. Unlike the GraphQL [`setRepositoryPermissionsForUsers`](#setting-repository-permissions-for-users) mutation, this is not a single atomic change, and it only works for users who already exist in Sourcegraph. - -### Resource names - -Resources are identified by resource names: - -- **Repository**: `repositories/`, where the repository ID is numeric, for example `repositories/123`. See [Finding a repository's ID](#finding-a-repositorys-id). -- **User**: `users/`, `users/@`, or `users/`, for example `users/456`, `users/@alice`, or `users/alice@example.com`. -- **Permission**: `repositories//explicitRepoPermissions/`, where `` accepts the same formats as a user resource name without the `users/` prefix, for example `repositories/123/explicitRepoPermissions/@alice`. - -Responses always identify repositories and users by their numeric IDs. - -### Finding a repository's ID - -The Sourcegraph API does not yet support looking up a repository by name. You can get the numeric repository ID from the [GraphQL debug API](/api/graphql): +Repositories are identified by their numeric ID, for example `repositories/123`. The Sourcegraph API cannot look up repositories by name yet, so get the ID with the [GraphQL API](/api/graphql): ```graphql query { @@ -99,105 +67,42 @@ query { } ``` -### Granting a user access to a repository +For request examples and schemas, see `/api-reference` on your Sourcegraph instance (e.g. `https://sourcegraph.example.com/api-reference`). -The following example grants the user `alice` access to the repository with ID `123`. The other examples on this page use the same `SRC_ACCESS_TOKEN`. +The following operations are only available in the [GraphQL API](/api/graphql) for now. -```bash -export SRC_ACCESS_TOKEN="sgp_example" +## Setting a repository as unrestricted -curl -X POST "https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/CreateExplicitRepoPermission" \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "parent": "repositories/123", - "explicitRepoPermission": { "user": "users/@alice" } - }' -``` - -The response contains the created permission: - -```json -{ - "name": "repositories/123/explicitRepoPermissions/456", - "user": "users/456", - "repository": "repositories/123" -} -``` - -You can also use the user as the parent and specify the repository instead, for example `{"parent": "users/@alice", "explicitRepoPermission": {"repository": "repositories/123"}}`. - -If the user already has explicit access to the repository, the request fails with an `already_exists` error. The user must already exist in Sourcegraph; otherwise the request fails with a `not_found` error. - -### Listing explicit permissions - -To list every user with explicit access to a repository, use the repository as the parent: - -```bash -curl -X POST "https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/ListExplicitRepoPermissions" \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ "parent": "repositories/123", "pageSize": 100 }' -``` +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. -To list every repository a user has explicit access to, use the user as the parent, for example `{"parent": "users/@alice"}`. +For example: -```json -{ - "explicitRepoPermissions": [ - { - "name": "repositories/123/explicitRepoPermissions/456", - "user": "users/456", - "repository": "repositories/123" - } - ], - "nextPageToken": "..." +```graphql +mutation { + setRepositoryPermissionsUnrestricted( + repositories: ["", "", ""] + unrestricted: true + ) { + alwaysNil + } } ``` -To get the next page, repeat the request with `pageToken` set to the returned `nextPageToken`. When `nextPageToken` is empty or missing, there are no more results. - -The list only contains explicit permissions, including those granted to existing users with the GraphQL API. Permissions synced from code hosts, and [pending permissions](#setting-repository-permissions-for-users) that were later applied to a user, are not included. To list a user's stored permissions from all sources, see [Listing a user's authorized repositories](#listing-a-users-authorized-repositories). - -### Checking a single permission - -```bash -curl -X POST "https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/GetExplicitRepoPermission" \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ "name": "repositories/123/explicitRepoPermissions/@alice" }' -``` - -If the user does not have explicit access to the repository, the request fails with a `not_found` error. - -### Revoking a user's access to a repository - -```bash -curl -X POST "https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/DeleteExplicitRepoPermission" \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ "name": "repositories/123/explicitRepoPermissions/@alice" }' -``` - -A successful request returns an empty JSON object. Only explicit permissions can be revoked: if the user only has access through permissions synced from a code host, or has no access, the request fails with a `not_found` error. Revoking an explicit permission does not remove access the user has through synced permissions. - -## Capabilities only available in the GraphQL API +## Setting repository permissions for users -The following capabilities are not yet available in the Sourcegraph API. Use the [Sourcegraph GraphQL debug API](/api/graphql) for them. The GraphQL API does not provide compatibility guarantees, so prefer the Sourcegraph API for everything it supports. +Setting the permissions for a user can be accomplished with 2 [GraphQL API](/api/graphql) calls. -GraphQL operations identify repositories by their GraphQL ID, which you can get with the following query: +First, obtain the ID of the repository from its name: ```graphql query { - repository(name: "github.example.com/owner/repo") { + repository(name: "github.com/owner/repo") { id } } ``` -### Setting repository permissions for users - -The `setRepositoryPermissionsForUsers` mutation replaces a repository's explicit permissions with a new list of users in one call. Use it if you need to grant access to users who do not exist in Sourcegraph yet: users are identified by their `bindID`, and permissions for a `bindID` that does not match an existing user are stored as pending. Pending permissions for a username are applied when a matching user is created; pending permissions for an email address are applied when a user verifies that address. +Next, set the list of users allowed to view the repository: ```graphql mutation { @@ -210,28 +115,13 @@ mutation { } ``` -Now, only the users specified in the `userPermissions` parameter have explicit permissions for the repository. Other users can still view it if they have access through permissions synced from a code host, or if the repository is public. Sourcegraph automatically enforces these permissions for all operations. (Administrators bypass all permissions checks by default. See the [Administrators](/admin/permissions/#administrators) section) - -> NOTE: The mutation replaces all explicit permissions and pending permissions for the repository, including permissions granted with the Sourcegraph API. It also removes the repository's [unrestricted](#setting-a-repository-as-unrestricted) setting. +Now, only the users specified in the `userPermissions` parameter will be allowed to view the repository. Sourcegraph automatically enforces these permissions for all operations. (Administrators bypass all permissions checks by default. See the [Administrators](/admin/permissions/#site-administrators) section) -### 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. +You can call `setRepositoryPermissionsForUsers` repeatedly to set permissions for each repository, and whenever you want to change the list of authorized users. It is also the way to grant access to users who don't exist in Sourcegraph yet: permissions for a `bindID` without a matching user are stored as pending and applied when the user is created, or, for email `bindID`s, when the email is verified. -For example: - -```graphql -mutation { - setRepositoryPermissionsUnrestricted( - repositories: ["", "", ""] - unrestricted: true - ) { - alwaysNil - } -} -``` +> NOTE: `setRepositoryPermissionsForUsers` replaces all explicit permissions for the repository, including those granted with the Sourcegraph API. -### Setting sub-repository permissions for users +## 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. @@ -277,7 +167,7 @@ The default permission if a path is not specified is to deny access. ### Listing a user's authorized repositories -You may query the repositories a particular user has stored permissions for, from explicit permissions and from code host syncing, with the `authorizedUserRepositories` [GraphQL API](/api/graphql) query. It accepts a `username` or `email` parameter to specify the user, and returns pending permissions for users who do not exist yet. It does not include repositories the user can view only because they are public or unrestricted. +You may query the set of repositories visible to a particular user with the `authorizedUserRepositories` [GraphQL API](/api/graphql) query, which accepts a `username` or `email` parameter to specify the user: ```graphql query { From 088c7d4ae4dc1044477e4252c5cb6e2d0d2af9e8 Mon Sep 17 00:00:00 2001 From: Taras Yemets Date: Fri, 9 Oct 2026 14:27:28 +0000 Subject: [PATCH 5/8] Shorten the explicit permissions page further after review --- docs/admin/permissions/api.mdx | 25 +++++-------------------- 1 file changed, 5 insertions(+), 20 deletions(-) diff --git a/docs/admin/permissions/api.mdx b/docs/admin/permissions/api.mdx index 1f5ca73e6..c87ac04c4 100644 --- a/docs/admin/permissions/api.mdx +++ b/docs/admin/permissions/api.mdx @@ -36,8 +36,6 @@ The `bindID` value specifies how to uniquely identify users when setting permiss - `username`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their Sourcegraph usernames. Using usernames is **preferred**, as usernames are required to be unique for each user. - `email`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their email addresses (which must be verified primary emails associated with their Sourcegraph user account). This method can lead to unexpected results if there are multiple Sourcegraph user accounts with the same verified email address. Also, the email address is case-sensitive, so it should be exactly the same as set on the sourcegraph UI. -`bindID` applies to the GraphQL operations; the Sourcegraph API identifies users as `users/@`, `users/`, or `users/`. - After you enable the permissions API, you must [set permissions](#setting-repository-permissions-for-users) to allow users to view repositories (administrators bypass all permissions checks and can always view all repositories). > NOTE: If you were previously using [permissions syncing](/admin/permissions/syncing), e.g. syncing permissions from Github, then those permissions are used as the initial state after enabling explicit permissions. Otherwise, the initial state is for all repositories to have an empty set of authorized users, so users will not be able to view any repositories. @@ -46,18 +44,9 @@ After you enable the permissions API, you must [set permissions](#setting-reposi ## Managing explicit permissions -The Sourcegraph API requires an [access token](/cli/how-tos/creating-an-access-token) with the `externalapi:read` scope for read operations or the `externalapi:write` scope for write operations, for a user with the `REPO_PERMISSIONS` permission (administrators have it by default). - -Each operation is served at `/api/explicitrepopermissions.v1.Service/`: +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 (administrators have it by default). -| Operation | Description | -| ------------------------------ | --------------------------------------------------------- | -| `CreateExplicitRepoPermission` | Grant a user explicit access to a repository. | -| `DeleteExplicitRepoPermission` | Revoke a user's explicit access to a repository. | -| `GetExplicitRepoPermission` | Check whether a user has explicit access to a repository. | -| `ListExplicitRepoPermissions` | List explicit permissions for a repository or for a user. | - -Repositories are identified by their numeric ID, for example `repositories/123`. The Sourcegraph API cannot look up repositories by name yet, so get the ID with the [GraphQL API](/api/graphql): +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 { @@ -67,8 +56,6 @@ query { } ``` -For request examples and schemas, see `/api-reference` on your Sourcegraph instance (e.g. `https://sourcegraph.example.com/api-reference`). - The following operations are only available in the [GraphQL API](/api/graphql) for now. ## Setting a repository as unrestricted @@ -82,9 +69,7 @@ mutation { setRepositoryPermissionsUnrestricted( repositories: ["", "", ""] unrestricted: true - ) { - alwaysNil - } + ) } ``` @@ -117,9 +102,9 @@ mutation { Now, only the users specified in the `userPermissions` parameter will be allowed to view the repository. Sourcegraph automatically enforces these permissions for all operations. (Administrators bypass all permissions checks by default. See the [Administrators](/admin/permissions/#site-administrators) section) -You can call `setRepositoryPermissionsForUsers` repeatedly to set permissions for each repository, and whenever you want to change the list of authorized users. It is also the way to grant access to users who don't exist in Sourcegraph yet: permissions for a `bindID` without a matching user are stored as pending and applied when the user is created, or, for email `bindID`s, when the email is verified. +You can call `setRepositoryPermissionsForUsers` repeatedly to set permissions for each repository, and whenever you want to change the list of authorized users. Unlike the Sourcegraph API, it accepts users who don't exist in Sourcegraph yet; their permissions apply once a user with that username or verified email exists. -> NOTE: `setRepositoryPermissionsForUsers` replaces all explicit permissions for the repository, including those granted with the Sourcegraph API. +> NOTE: The mutation also removes permissions granted with the Sourcegraph API. ## Setting sub-repository permissions for users From 8acf6ee1a9b414a434127fd4bc8b48afddf0f6e7 Mon Sep 17 00:00:00 2001 From: Taras Yemets Date: Fri, 9 Oct 2026 15:00:22 +0000 Subject: [PATCH 6/8] Drop the Sourcegraph API comparison from the pending permissions sentence --- docs/admin/permissions/api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/permissions/api.mdx b/docs/admin/permissions/api.mdx index c87ac04c4..a738501f1 100644 --- a/docs/admin/permissions/api.mdx +++ b/docs/admin/permissions/api.mdx @@ -102,7 +102,7 @@ mutation { Now, only the users specified in the `userPermissions` parameter will be allowed to view the repository. Sourcegraph automatically enforces these permissions for all operations. (Administrators bypass all permissions checks by default. See the [Administrators](/admin/permissions/#site-administrators) section) -You can call `setRepositoryPermissionsForUsers` repeatedly to set permissions for each repository, and whenever you want to change the list of authorized users. Unlike the Sourcegraph API, it accepts users who don't exist in Sourcegraph yet; their permissions apply once a user with that username or verified email exists. +You can call `setRepositoryPermissionsForUsers` repeatedly to set permissions for each repository, and whenever you want to change the list of authorized users. It also accepts users who don't exist in Sourcegraph yet; their permissions apply once a user with that username or verified email exists. > NOTE: The mutation also removes permissions granted with the Sourcegraph API. From 384994a7568f38842a83d28a4c3a08820a371b2c Mon Sep 17 00:00:00 2001 From: Taras Yemets Date: Fri, 9 Oct 2026 15:06:36 +0000 Subject: [PATCH 7/8] Drop the pending permissions sentence --- docs/admin/permissions/api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/permissions/api.mdx b/docs/admin/permissions/api.mdx index a738501f1..6bfc6f62f 100644 --- a/docs/admin/permissions/api.mdx +++ b/docs/admin/permissions/api.mdx @@ -102,7 +102,7 @@ mutation { Now, only the users specified in the `userPermissions` parameter will be allowed to view the repository. Sourcegraph automatically enforces these permissions for all operations. (Administrators bypass all permissions checks by default. See the [Administrators](/admin/permissions/#site-administrators) section) -You can call `setRepositoryPermissionsForUsers` repeatedly to set permissions for each repository, and whenever you want to change the list of authorized users. It also accepts users who don't exist in Sourcegraph yet; their permissions apply once a user with that username or verified email exists. +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. From 17c15c76a285c2edb6093fd04046b67a3adf228b Mon Sep 17 00:00:00 2001 From: Taras Yemets Date: Fri, 9 Oct 2026 15:10:29 +0000 Subject: [PATCH 8/8] Link the REPO_PERMISSIONS permission to access control --- docs/admin/permissions/api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/permissions/api.mdx b/docs/admin/permissions/api.mdx index 6bfc6f62f..2ba287250 100644 --- a/docs/admin/permissions/api.mdx +++ b/docs/admin/permissions/api.mdx @@ -44,7 +44,7 @@ After you enable the permissions API, you must [set permissions](#setting-reposi ## 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 (administrators have it by default). +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):