Skip to content

OAuthService.md

Latest commit

 

History

History
245 lines (177 loc) · 14 KB

OAuthService.md

File metadata and controls

245 lines (177 loc) · 14 KB
Raw

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.

{% hint style="info" %} 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 {% endhint %}

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" });

// A second, independent login (e.g. another Linear workspace):
const secondWorkspace = OAuthService.linear({
  scope: "read write",
  providerId: "linear-workspace-2",
  extraParameters: { prompt: "consent" },
});

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 Name Description Type
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 Name Description Type
clientId* The app's client ID string
scope* The scope of the access requested from the provider string | Array<string>
providerId The provider ID used to namespace the token storage of the internally-constructed OAuth.PKCEClient. Defaults to the service's name (e.g. linear). Override it to keep several independent logins for the same provider (e.g. one per workspace). string
extraParameters Extra parameters for the authorization request, merged over the provider's defaults (caller wins) Record<string, 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 Name Description Type
scope* The scope of the access requested from the provider string | Array<string>
providerId The provider ID used to namespace the token storage of the internally-constructed OAuth.PKCEClient. Defaults to the service's name (e.g. linear). Override it to keep several independent logins for the same provider (e.g. one per workspace). string
extraParameters Extra parameters for the authorization request, merged over the provider's defaults (caller wins) Record<string, 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