0
# Slack OAuth
1

2
Slack OAuth is the official TypeScript/JavaScript library for handling Slack app OAuth installations. It provides a complete OAuth 2.0 implementation with support for both modern Slack Apps (v2) and Classic Slack apps (v1), state management for CSRF protection, and flexible storage solutions for installation data.
3

4
## Package Information
5

6
- **Package Name**: @slack/oauth
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @slack/oauth`
10

11
## Core Imports
12

13
```typescript
14
import { InstallProvider } from "@slack/oauth";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { InstallProvider } = require("@slack/oauth");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { InstallProvider } from "@slack/oauth";
27

28
// Initialize the OAuth provider
29
const installer = new InstallProvider({
30
  clientId: process.env.SLACK_CLIENT_ID,
31
  clientSecret: process.env.SLACK_CLIENT_SECRET,
32
  stateSecret: "my-state-secret",
33
});
34

35
// Handle install path
36
app.get("/slack/install", async (req, res) => {
37
  await installer.handleInstallPath(req, res, undefined, {
38
    scopes: ["chat:write", "commands"],
39
  });
40
});
41

42
// Handle OAuth callback
43
app.get("/slack/oauth_redirect", async (req, res) => {
44
  await installer.handleCallback(req, res);
45
});
46

47
// Authorize requests
48
const authResult = await installer.authorize({
49
  teamId: "T1234567890",
50
  isEnterpriseInstall: false,
51
});
52
```
53

54
## Architecture
55

56
Slack OAuth is built around several core components:
57

58
- **InstallProvider**: Main OAuth coordinator handling the complete OAuth flow
59
- **Installation Storage**: Pluggable storage interfaces for persisting app installation data
60
- **State Management**: CSRF protection through encrypted state parameters
61
- **OAuth Versions**: Support for both OAuth v1 (Classic Apps) and v2 (Granular Bot Permissions)
62
- **Error Handling**: Comprehensive error types for OAuth-specific failures
63

64
## Capabilities
65

66
### OAuth Flow Management
67

68
Complete OAuth 2.0 flow implementation with install URL generation, callback handling, and token exchange. Handles both bot and user token installation patterns.
69

70
```typescript { .api }
71
class InstallProvider {
72
  constructor(options: InstallProviderOptions);
73
  async handleInstallPath(
74
    req: IncomingMessage, 
75
    res: ServerResponse, 
76
    installOptions?: InstallURLOptions
77
  ): Promise<void>;
78
  async generateInstallUrl(options: InstallURLOptions): Promise<string>;
79
  async handleCallback(
80
    req: IncomingMessage, 
81
    res: ServerResponse, 
82
    options?: CallbackOptions
83
  ): Promise<void>;
84
  async authorize(source: InstallationQuery<boolean>): Promise<AuthorizeResult>;
85
}
86

87
interface InstallProviderOptions {
88
  clientId: string;
89
  clientSecret: string;
90
  stateSecret?: string;
91
  installationStore?: InstallationStore;
92
  stateStore?: StateStore;
93
  authVersion?: "v1" | "v2";
94
  // ... additional options
95
}
96
```
97

98
[OAuth Flow Management](./oauth-flow.md)
99

100
### Installation Storage
101

102
Flexible storage system for persisting and retrieving app installation data including tokens, team information, and user details.
103

104
```typescript { .api }
105
interface InstallationStore {
106
  storeInstallation<AuthVersion extends "v1" | "v2">(
107
    installation: Installation<AuthVersion, boolean>,
108
    logger?: Logger
109
  ): Promise<void>;
110
  fetchInstallation(
111
    query: InstallationQuery<boolean>,
112
    logger?: Logger
113
  ): Promise<Installation<"v1" | "v2", boolean>>;
114
  deleteInstallation?(
115
    query: InstallationQuery<boolean>,
116
    logger?: Logger
117
  ): Promise<void>;
118
}
119

120
interface Installation<AuthVersion extends "v1" | "v2", IsEnterpriseInstall extends boolean> {
121
  team: IsEnterpriseInstall extends true ? undefined : { id: string; name?: string };
122
  enterprise?: { id: string; name?: string };
123
  bot?: { token: string; scopes: string[]; id: string; userId: string };
124
  user?: { token: string; scopes: string[]; id: string };
125
  // ... additional properties
126
}
127
```
128

129
[Installation Storage](./installation-storage.md)
130

131
### State Management
132

133
CSRF protection through encrypted state parameters that securely transfer installation options between OAuth endpoints.
134

135
```typescript { .api }
136
interface StateStore {
137
  generateStateParam(
138
    installOptions: InstallURLOptions,
139
    now: Date
140
  ): Promise<string>;
141
  verifyStateParam(now: Date, state: string): Promise<InstallURLOptions>;
142
}
143

144
interface StateObj {
145
  now: Date;
146
  installOptions: InstallURLOptions;
147
  random?: string | number;
148
}
149
```
150

151
[State Management](./state-management.md)
152

153
### Error Handling
154

155
Comprehensive error types with specific codes for different OAuth failure scenarios.
156

157
```typescript { .api }
158
enum ErrorCode {
159
  InstallerInitializationError = "slack_oauth_installer_initialization_error";
160
  AuthorizationError = "slack_oauth_installer_authorization_error";
161
  GenerateInstallUrlError = "slack_oauth_generate_url_error";
162
  MissingStateError = "slack_oauth_missing_state";
163
  InvalidStateError = "slack_oauth_invalid_state";
164
  MissingCodeError = "slack_oauth_missing_code";
165
  UnknownError = "slack_oauth_unknown_error";
166
}
167

168
interface CodedError extends Error {
169
  code: string;
170
}
171
```
172

173
[Error Handling](./error-handling.md)