OAuth Apps

OAuth Apps let you build rich third-party experiences that interact with Sourcegraph on behalf of end-users while honoring their repository permissions. Every API request made with an OAuth access token is evaluated against the same authorization rules that apply inside the Sourcegraph UI, so your integration only sees the code each user is allowed to see.

This makes OAuth the preferred choice for any multi-user integration like browser extensions, IDE plugins, chatbots, internal tools, or SaaS platforms where you need to:

• Authenticate users with familiar Sourcegraph credentials
• Operate without ever handling or storing users' passwords
• Rely on short-lived, scoped tokens that can be revoked at any time
• Guarantee that repository visibility and other access controls are enforced automatically

OAuth Apps are in compliance with standards including RFC 6749, RFC 7636 (PKCE), and RFC 8628 (Device Authorization Grant).

Consider using M2M (client-credentials) service-account tokens or traditional access tokens for server-to-server communication, automated scripts, CI/CD pipelines, or single-user applications that do not require per-user permission checks. See service accounts for details.

Creating an OAuth App

Site admins can create OAuth Apps in the site admin area:

1. Navigate to Site admin > OAuth clients

2. Click Create OAuth client

3. Provide the following information:

   • Name: A descriptive name for your application
   • Description: (Optional) Additional details about the app's purpose
   • Redirect URI: The URL where users will be redirected after authorization
   • Client type: Choose between Public or Private
   • Scopes: Select the permissions your app needs

4. Click Create to generate the OAuth client

After creation, you'll receive:

• Client ID: Public identifier for your application
• Client Secret: (Private clients only) Secret key for authentication

Client Types

Public Clients

Public clients are designed for applications that cannot securely store client secrets:

• Browser-based applications (SPAs)
• Mobile applications
• Desktop applications

Public clients:

• Do not receive a client secret
• Must use PKCE (Proof Key for Code Exchange) for security
• Support RFC 8628 Device Authorization Grant flow
• Are suitable for environments where the client code is publicly accessible

Private Clients

Private clients can securely store client secrets:

• Server-side web applications
• Backend services
• Secure server environments

Private clients:

• Receive both client ID and client secret
• Can use the standard authorization code flow (PKCE strongly recommended)
• Allow client authentication with a secret and server-side code exchange

Available Scopes

When creating an OAuth app, select the minimum scopes necessary for your application:

OAuth endpoints reference

OAuth Flow Examples

Using OAuth Tokens

Once you have an OAuth access token, use it to authenticate API requests:

GraphQL API

BASH
curl -H 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
  -d '{"query": "query { currentUser { username } }"}' \
  https://sourcegraph.example.com/.api/graphql

Streaming API

BASH
curl -H 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
  -H 'Accept: text/event-stream' \
  --get \
  --url 'https://sourcegraph.example.com/.api/search/stream' \
  --data-urlencode 'q=your search query'

Token Management

Token Expiration

OAuth access tokens issued by Sourcegraph are always short-lived with a fixed expiration time. Non-expiring access tokens are not available through the OAuth flow. Access tokens typically expire after 1 hour.

Refresh Tokens

Refresh tokens are issued alongside every access token and must be used to obtain new access tokens before the current token expires:

BASH
curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" # Only for private clients

Important: Always store the new refresh token returned in the response, as it may differ from the one you used in the request. Every refresh token is strictly one-time use, your application needs to handle the case when it's possible to have multiple processes initiating the token refresh process because only one of them will succeed for the same refresh token.

Token Expiration Handling

Applications must proactively check token expiration and refresh tokens before they expire:

1. Monitor the expires_in field from token responses to track when tokens expire
2. Refresh proactively by checking expiration time before each API call
3. Use a safety buffer of 60+ seconds to avoid race conditions
4. Handle 401 responses by refreshing the token and retrying the request

Token Revocation

Users can revoke OAuth consents through their account settings, or your integration can programmatically revoke tokens:

BASH
curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_TOKEN_OR_REFRESH_TOKEN" \
  -d "token_type_hint=access_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" # Only for private clients