Explicit permissions API

Sourcegraph allows site administrators to explicitly set repository permissions through the Sourcegraph API. This is an alternative to other mechanisms, which involve directly talking to the code host.

The Sourcegraph API is a versioned external API introduced in Sourcegraph 7.0. The full API surface, including the operations documented here, can be browsed at /api-reference on your instance (e.g. https://sourcegraph.example.com/api-reference), where you can also download the OpenAPI schema.

NOTE: The Sourcegraph GraphQL debug API also exposes some explicit-permissions operations for diagnostics and tooling, but the Sourcegraph API is the recommended interface for integrations.

Permissions mechanisms in parallel

If you want to use explicit permissions management alongside permissions synchronised from code hosts, read section permission mechanisms in parallel here.

Recommendations

We only recommend using the explicit permissions API in cases where the other methods are not possible or effective. For example, if a code host does not support permission syncing/webhooks, or if it would take an unreasonable amount of resources/time to sync permissions from the code host.

It's also a good idea to use the explicit permissions API if the source of truth for the code host permissions is already defined in some external system, e.g. LDAP group membership. In that case, it might be less resource intensive to sync the permissions from the external source of truth directly via a periodically running routine.

SLA

Sourcegraph's SLA is that p95 of write requests to the explicit permissions API will be resolved within 10 seconds.

Sourcegraph does not provide an SLA for how fresh the permissions are, since the data is provided as-is to the API.

Disadvantages

It is important to note that when using the explicit permissions API, the permissions are written to the database as provided, without further verification that such permissions exist on the code host side.

Keeping the permissions in sync and fresh is the responsibility of the site admins.

Licensing

The explicit permissions API requires the Explicit Permissions API license feature. Calls made on an instance whose license does not include this feature fail with a FailedPrecondition error.

Configuration

To enable the permissions API, add the following to the site configuration:

JSON
"permissions.userMapping": {
    "enabled": true,
    "bindID": "username"
}

The bindID value specifies how to uniquely identify users when setting permissions:

• username: You can set permissions 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 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 in the Sourcegraph UI.

After you enable the permissions API, you must set permissions to allow users to view repositories (site admins bypass all permissions checks and can always view all repositories).

NOTE: If you were previously using 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.

Authentication and authorization

The Sourcegraph API accepts token-based authentication only — browser session cookies are not accepted. Pass a Sourcegraph access token as a Bearer token in the Authorization header:

SHELL
Authorization: Bearer <token>

OAuth tokens and the Authorization: token <token> header form are also supported.

Token scopes

Calls to the explicit permissions API require the following access-token scopes:

• Reads (GetExplicitRepoPermission, ListExplicitRepoPermissions) require the externalapi:read scope.
• Writes (CreateExplicitRepoPermission, DeleteExplicitRepoPermission) require the externalapi:write scope.

Broadly-scoped user:all tokens are still accepted, but their use against the Sourcegraph API is recorded in the audit log. We recommend using narrowly scoped tokens.

RBAC permissions

In addition to a valid token, the calling user must hold the appropriate RBAC permission:

• REPO_PERMISSIONS#READ for read operations.
• REPO_PERMISSIONS#WRITE for write operations.

Explicit repository permissions operations

The explicit permissions API is served under /api/ on your Sourcegraph instance. Requests and responses are JSON, sent over HTTPS using POST. The authoritative schema is published at /api-reference; the summary below documents the operations that are most commonly used.

Resource names

Resources are identified using AIP-122 style resource names:

When you create or read a permission, the server returns the canonical form (repositories/{repo_id}/explicitRepoPermissions/{numeric_user_id}), even if the request used an alias such as @alice.

Operations

GetExplicitRepoPermission

Request:

JSON
{ "name": "repositories/123/explicitRepoPermissions/@alice" }

Response:

JSON
{
  "name": "repositories/123/explicitRepoPermissions/456",
  "user": "users/456",
  "repository": "repositories/123"
}

ListExplicitRepoPermissions

Lists explicit permissions under a parent, which may be either a repository or a user. Results are paginated; an empty next_page_token means no more results.

Request — list users with explicit access to a repository:

JSON
{ "parent": "repositories/123", "page_size": 50, "page_token": "" }

Request — list repositories a user has explicit access to:

JSON
{ "parent": "users/@alice", "page_size": 50 }

Response:

JSON
{
  "explicit_repo_permissions": [
    {
      "name": "repositories/123/explicitRepoPermissions/456",
      "user": "users/456",
      "repository": "repositories/123"
    }
  ],
  "next_page_token": ""
}

CreateExplicitRepoPermission

Grants a user access to a repository. The parent can be either side of the relationship, with the other side specified inside explicit_repo_permission.

Request — parent is a repository:

JSON
{
  "parent": "repositories/123",
  "explicit_repo_permission": { "user": "users/@alice" }
}

Request — parent is a user:

JSON
{
  "parent": "users/@alice",
  "explicit_repo_permission": { "repository": "repositories/123" }
}

The response is the created ExplicitRepoPermission resource.

DeleteExplicitRepoPermission

Revokes a user's access to a repository.

Request:

JSON
{ "name": "repositories/123/explicitRepoPermissions/@alice" }

Response:

JSON
{}

Examples

The examples below use a placeholder instance at https://sourcegraph.example.com and assume a Sourcegraph access token is available in the SRC_ACCESS_TOKEN environment variable.

Grant alice access to repository 123

BASH
curl -X POST \
  -H "Authorization: Bearer $SRC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": "repositories/123",
    "explicit_repo_permission": { "user": "users/@alice" }
  }' \
  https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/CreateExplicitRepoPermission

List all users with explicit access to repository 123

BASH
curl -X POST \
  -H "Authorization: Bearer $SRC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "parent": "repositories/123", "page_size": 50 }' \
  https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/ListExplicitRepoPermissions

To page through more than page_size results, pass the next_page_token returned by the previous response as page_token in the next request.

List all repositories alice has explicit access to

BASH
curl -X POST \
  -H "Authorization: Bearer $SRC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "parent": "users/@alice", "page_size": 50 }' \
  https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/ListExplicitRepoPermissions

Revoke alice's access to repository 123

BASH
curl -X POST \
  -H "Authorization: Bearer $SRC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "repositories/123/explicitRepoPermissions/@alice" }' \
  https://sourcegraph.example.com/api/explicitrepopermissions.v1.Service/DeleteExplicitRepoPermission

Capabilities not yet available in the Sourcegraph API

The following capabilities related to explicit permissions are not yet exposed through the Sourcegraph API. They are currently available only through the Sourcegraph GraphQL debug API. We plan to port these capabilities to the Sourcegraph API in a future release; until then, prefer the Sourcegraph GraphQL debug API for these specific operations.

Marking a repository as unrestricted

It can occasionally be useful to mark a repository as unrestricted, meaning that it is available to all Sourcegraph users regardless of any explicit or synced permissions. Setting unrestricted back to false restores the previous behaviour.

This capability is currently only available via the Sourcegraph GraphQL debug API.

Sub-repository permissions (experimental)

Sourcegraph also supports permissions at a per-file or per-directory level within a repository. This is an experimental feature; enable it in the site configuration with:

JSON
"experimentalFeatures": {
    "subRepoPermissions": { "enabled": true }
}

Sub-repo rules use glob syntax; a - prefix denies a path, rules are evaluated in the order they are specified, and any path that does not match a rule defaults to deny. A user who has general access to the repository but has no sub-repo rules set is granted access to the entire repository contents.

Setting sub-repository permissions is currently only available via the Sourcegraph GraphQL debug API.