OAuthService

The OAuthService class is designed to abstract the OAuth authorization process using the PKCE (Proof Key for Code Exchange) flow, simplifying the integration with various OAuth providers such as Asana, GitHub, and others.

Use OAuthServiceOptions to configure the OAuthService class.

Example

const client = new OAuth.PKCEClient({
  redirectMethod: OAuth.RedirectMethod.Web,
  providerName: "GitHub",
  providerIcon: "extension_icon.png",
  providerId: "github",
  description: "Connect your GitHub account",
});

const github = new OAuthService({
  client,
  clientId: "7235fe8d42157f1f38c0",
  scope: "notifications repo read:org read:user read:project",
  authorizeUrl: "https://github.oauth.raycast.com/authorize",
  tokenUrl: "https://github.oauth.raycast.com/token",
});

Signature

constructor(options: OAuthServiceOptions): OAuthService

Methods

authorize

Initiates the OAuth authorization process or refreshes existing tokens if necessary. Returns a promise that resolves with the access token from the authorization flow.

Signature

OAuthService.authorize(): Promise<string>;

Example

const accessToken = await oauthService.authorize();

Built-in Services

Some services are exposed as static properties in OAuthService to make it easy to authenticate with them:

Asana, GitHub, Linear, and Slack already have an OAuth app configured by Raycast so that you can use them right of the box by specifing only the permission scopes. You are still free to create an OAuth app for them if you want.

Google, Jira and Zoom don't have an OAuth app configured by Raycast so you'll have to create one if you want to use them.

Use ProviderOptions or ProviderWithDefaultClientOptions to configure these built-in services.

Asana

Signature

OAuthService.asana: (options: ProviderWithDefaultClientOptions) => OAuthService

Example

const asana = OAuthService.asana({ scope: "default" });

GitHub

Signature

OAuthService.github: (options: ProviderWithDefaultClientOptions) => OAuthService

Example

const github = OAuthService.github({ scope: "repo user" });

Google

Google has verification processes based on the required scopes for your extension. Therefore, you need to configure your own client for it.

Creating your own Google client ID is more tedious than other processes, so we’ve created a page to assist you: Getting a Google client ID

Signature

OAuthService.google: (options: ProviderOptions) => OAuthService

Example

const google = OAuthService.google({
  clientId: "custom-client-id",
  scope: "https://www.googleapis.com/auth/drive.readonly",
});

Jira

Jira requires scopes to be enabled manually in the OAuth app settings. Therefore, you need to configure your own client for it.

Signature

OAuthService.jira: (options: ProviderOptions) => OAuthService

Example

const jira = OAuthService.jira({
  clientId: "custom-client-id",
  scope: "read:jira-user read:jira-work offline_access",
});

Linear

Signature

OAuthService.linear: (options: ProviderOptions) => OAuthService

Example

const linear = OAuthService.linear({ scope: "read write" });

Slack

Signature

OAuthService.slack: (options: ProviderWithDefaultClientOptions) => OAuthService

Example

const slack = OAuthService.slack({ scope: "emoji:read" });

Zoom

Zoom requires scopes to be enabled manually in the OAuth app settings. Therefore, you need to configure your own client for it.

Signature

OAuthService.zoom: (options: ProviderOptions) => OAuthService

Example

const zoom = OAuthService.zoom({
  clientId: "custom-client-id",
  scope: "meeting:write",
});

Types

OAuthServiceOptions

Property NameDescriptionType

client*

The PKCE Client defined using OAuth.PKCEClient from @raycast/api

OAuth.PKCEClient

clientId*

The app's client ID

string

scope*

The scope of the access requested from the provider

string | Array<string>

authorizeUrl*

The URL to start the OAuth flow

string

tokenUrl*

The URL to exchange the authorization code for an access token

string

refreshTokenUrl

The URL to refresh the access token if applicable

string

personalAccessToken

A personal token if the provider supports it

string

onAuthorize

A callback function that is called once the user has been properly logged in through OAuth when used with withAccessToken

string

extraParameters

The extra parameters you may need for the authorization request

Record<string, string>

bodyEncoding

Specifies the format for sending the body of the request.

json | url-encoded

tokenResponseParser

Some providers returns some non-standard token responses. Specifies how to parse the JSON response to get the access token

(response: unknown) => OAuth.TokenResponse

tokenRefreshResponseParser

Some providers returns some non-standard refresh token responses. Specifies how to parse the JSON response to get the access token

(response: unknown) => OAuth.TokenResponse

ProviderOptions

Property NameDescriptionType

clientId*

The app's client ID

string

scope*

The scope of the access requested from the provider

string | Array<string>

authorizeUrl*

The URL to start the OAuth flow

string

tokenUrl*

The URL to exchange the authorization code for an access token

string

refreshTokenUrl

The URL to refresh the access token if applicable

string

personalAccessToken

A personal token if the provider supports it

string

onAuthorize

A callback function that is called once the user has been properly logged in through OAuth when used with withAccessToken

string

bodyEncoding

Specifies the format for sending the body of the request.

json | url-encoded

tokenResponseParser

Some providers returns some non-standard token responses. Specifies how to parse the JSON response to get the access token

(response: unknown) => OAuth.TokenResponse

tokenRefreshResponseParser

Some providers returns some non-standard refresh token responses. Specifies how to parse the JSON response to get the access token

(response: unknown) => OAuth.TokenResponse

ProviderWithDefaultClientOptions

Property NameDescriptionType

scope*

The scope of the access requested from the provider

string | Array<string>

clientId

The app's client ID

string

authorizeUrl

The URL to start the OAuth flow

string

tokenUrl

The URL to exchange the authorization code for an access token

string

refreshTokenUrl

The URL to refresh the access token if applicable

string

personalAccessToken

A personal token if the provider supports it

string

onAuthorize

A callback function that is called once the user has been properly logged in through OAuth when used with withAccessToken

string

bodyEncoding

Specifies the format for sending the body of the request.

json | url-encoded

tokenResponseParser

Some providers returns some non-standard token responses. Specifies how to parse the JSON response to get the access token

(response: unknown) => OAuth.TokenResponse

tokenRefreshResponseParser

Some providers returns some non-standard refresh token responses. Specifies how to parse the JSON response to get the access token

(response: unknown) => OAuth.TokenResponse

Last updated