Explicit permissions API

Sourcegraph supports explicitly setting repository permissions via the Sourcegraph API. This is an alternative to other mechanisms, which involve directly talking to the code host.

The Sourcegraph API is an external API introduced in Sourcegraph 7.0 for custom integrations. The authoritative schema for the operations described on this page — including request and response types — can be browsed at /api-reference on your instance (for example, https://sourcegraph.example.com/api-reference), where you can also download the OpenAPI schema.

NOTE: The explicit permissions API requires the Explicit Permissions API license feature. Calls made on an instance without this license feature fail with a FailedPrecondition error.

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 to use the explicit permissions API in cases, where the other methods are not possible or effective. E.g. 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 codehost 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 external source of truth directly via a periodically running routine.

SLA

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

Sourcegraph does not provide 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 do exist on the code host side.

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

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 on 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.

API surface

Explicit repository permissions are managed through the following operations on the Sourcegraph API. Each operation is served at /api/<fully-qualified-method> on your instance, accepts a JSON request body via HTTP POST, and returns a JSON response. The authoritative schema is available at /api-reference.

Resource names

Resources are addressed using Google AIP-122 style resource names:

• Repository: repositories/{numeric_id} — for example, repositories/123.
• User: users/{numeric_id}, users/@{username}, or users/{email} — for example, users/456, users/@alice, or users/alice@example.com.
• Permission: repositories/{repo_id}/explicitRepoPermissions/{user_id_or_identifier} — for example, repositories/123/explicitRepoPermissions/@alice or repositories/123/explicitRepoPermissions/456.

Authentication

Requests to the Sourcegraph API must authenticate with a token; browser session cookies are not accepted. Pass a Sourcegraph access token as a Bearer token in the Authorization header:

HTTP
Authorization: Bearer <token>

OAuth tokens and the standard Sourcegraph HTTP header authentication formats are also accepted.

Token scopes

Tokens used with these operations must carry the appropriate scopes:

• Read operations (GetExplicitRepoPermission, ListExplicitRepoPermissions) require the externalapi:read scope.
• Write operations (CreateExplicitRepoPermission, DeleteExplicitRepoPermission) require the externalapi:write scope.

Broadly-scoped user:all tokens continue to be accepted, but their use against the Sourcegraph API is audit-logged. We recommend issuing scoped tokens to integrations whenever possible.

RBAC permissions

In addition to a valid token scope, the calling user must also hold the corresponding RBAC permission:

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

Site admins bypass all permissions checks by default. See the Site administrators section.

Operations

GetExplicitRepoPermission

Look up a single explicit repository permission by name.

Request

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

Response

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

ListExplicitRepoPermissions

List the explicit permissions associated with a repository or with a user. The parent field selects the listing dimension and may be either a repository or a user resource name.

Request — by repository

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

Request — by user

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": "..."
}

Pass the returned next_page_token back in a subsequent request to fetch the next page. An empty next_page_token indicates that there are no more results.

CreateExplicitRepoPermission

Grant a user explicit access to a repository. The parent may be either the repository or the user; the other side of the relationship is supplied in 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"
  }
}

Response

The created ExplicitRepoPermission:

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

DeleteExplicitRepoPermission

Revoke a user's explicit access to a repository.

Request

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

Response

JSON
{}

Examples

The examples below use https://sourcegraph.example.com as a placeholder for your instance, and assume your access token is exported as SRC_ACCESS_TOKEN.

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

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 covered by the Sourcegraph API

The capabilities below are not yet available on the Sourcegraph API and are currently only accessible through the Sourcegraph GraphQL debug API. They will be ported to the Sourcegraph API in a future release.

Marking a repository as unrestricted

Sometimes it can be useful to mark a repository as unrestricted, meaning that it is available to all Sourcegraph users regardless of 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:

GRAPHQL
mutation {
  setRepositoryPermissionsUnrestricted(
    repositories: ["<repo ID>", "<repo ID>"]
    unrestricted: true
  )
}

Sub-repository permissions

Sourcegraph supports experimental per-file/directory permissions within a repository. To enable this feature, add the following to the site configuration:

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

Paths are specified in glob syntax. A - prefix denies a path, rules are applied in the order in which they are listed, and any path that does not match a rule defaults to deny. A user who has general access to a repository but has no sub-repo rules set retains access to the entire repository.

This capability is currently only available via the Sourcegraph GraphQL debug API. For example, the following grants alice access to every file in the repository except README.md:

GRAPHQL
mutation {
  setSubRepositoryPermissionsForUsers(
    repository: "<repo ID>"
    userPermissions: [{ bindID: "alice", paths: ["/**", "-/README.md"] }]
  ) {
    alwaysNil
  }
}

NOTE: The Sourcegraph GraphQL debug API is intended for diagnostics and simple tooling and does not provide backwards-compatibility guarantees. Prefer the Sourcegraph API for production integrations.