0
# Authentication & Authorization
1

2
User and community authentication with VK platform including access token management, permission scoping, and OAuth integration for secure API access.
3

4
## Capabilities
5

6
### User Authentication
7

8
Get user access tokens with specific permission scopes for accessing VK API on behalf of users.
9

10
```typescript { .api }
11
/**
12
 * Get user access token for VK API access
13
 * @param props.app_id - VK application ID
14
 * @param props.scope - Requested permission scopes
15
 * @returns Access token with granted scopes and expiration
16
 */
17
function send(method: 'VKWebAppGetAuthToken', props: {
18
  app_id: number;
19
  scope: PersonalAuthScope | string;
20
}): Promise<{
21
  access_token: string;
22
  scope: string;
23
  expires?: number;
24
  status?: boolean;
25
}>;
26

27
type PersonalAuthScope = 
28
  | 'friends'    // Access to friends list
29
  | 'photos'     // Access to user photos
30
  | 'video'      // Access to user videos
31
  | 'stories'    // Access to user stories
32
  | 'pages'      // Access to user pages
33
  | 'status'     // Access to user status
34
  | 'notes'      // Access to user notes
35
  | 'wall'       // Access to user wall
36
  | 'docs'       // Access to user documents
37
  | 'groups'     // Access to user groups
38
  | 'stats'      // Access to user statistics
39
  | 'market';    // Access to user market
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
// Basic user authentication
46
const authResult = await bridge.send('VKWebAppGetAuthToken', {
47
  app_id: 51665960,
48
  scope: 'friends,photos'
49
});
50

51
console.log('Access token:', authResult.access_token);
52
console.log('Granted scopes:', authResult.scope);
53
console.log('Expires in:', authResult.expires, 'seconds');
54

55
// Single scope authentication
56
const photosAuth = await bridge.send('VKWebAppGetAuthToken', {
57
  app_id: 51665960,
58
  scope: 'photos'
59
});
60

61
// Multiple scopes
62
const fullAuth = await bridge.send('VKWebAppGetAuthToken', {
63
  app_id: 51665960,
64
  scope: 'friends,photos,wall,groups'
65
});
66

67
// Use token for VK API calls
68
const apiResult = await bridge.send('VKWebAppCallAPIMethod', {
69
  method: 'users.get',
70
  params: {
71
    access_token: authResult.access_token,
72
    v: '5.131'
73
  }
74
});
75
```
76

77
### Community Authentication
78

79
Get community access tokens for managing communities and accessing community-specific features.
80

81
```typescript { .api }
82
/**
83
 * Get community access token for community management
84
 * @param props.app_id - VK application ID
85
 * @param props.group_id - Community ID to get token for
86
 * @param props.scope - Requested community permission scopes
87
 * @returns Community access token with granted scopes
88
 */
89
function send(method: 'VKWebAppGetCommunityToken', props: {
90
  app_id: number;
91
  group_id: number;
92
  scope: CommunityAuthScope | string;
93
}): Promise<{
94
  access_token: string;
95
  scope: string;
96
}>;
97

98
type CommunityAuthScope = 
99
  | 'stories'     // Manage community stories
100
  | 'photos'      // Manage community photos
101
  | 'app_widget'  // Manage community app widget
102
  | 'messages'    // Access to community messages
103
  | 'docs'        // Manage community documents
104
  | 'manage';     // Full community management
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
// Get community management token
111
const communityAuth = await bridge.send('VKWebAppGetCommunityToken', {
112
  app_id: 51665960,
113
  group_id: 123456789,
114
  scope: 'photos,messages,manage'
115
});
116

117
console.log('Community token:', communityAuth.access_token);
118
console.log('Granted scopes:', communityAuth.scope);
119

120
// Use for community API calls
121
const communityInfo = await bridge.send('VKWebAppCallAPIMethod', {
122
  method: 'groups.getById',
123
  params: {
124
    access_token: communityAuth.access_token,
125
    group_id: '123456789',
126
    v: '5.131'
127
  }
128
});
129

130
// Post to community wall
131
const wallPost = await bridge.send('VKWebAppCallAPIMethod', {
132
  method: 'wall.post',
133
  params: {
134
    access_token: communityAuth.access_token,
135
    owner_id: '-123456789', // Negative for communities
136
    message: 'Hello from our VK Mini App!',
137
    v: '5.131'
138
  }
139
});
140
```
141

142
### Permission Management
143

144
Check and manage application permissions and granted scopes.
145

146
```typescript { .api }
147
/**
148
 * Check which permission scopes are allowed for the app
149
 * @param props.scopes - Comma-separated list of scopes to check
150
 * @returns List of scopes with their availability status
151
 */
152
function send(method: 'VKWebAppCheckAllowedScopes', props: {
153
  scopes: string;
154
}): Promise<{
155
  result: VKWebAppCheckAllowedScopesResponseEntry[];
156
}>;
157

158
interface VKWebAppCheckAllowedScopesResponseEntry {
159
  scope: string;
160
  allowed: boolean;
161
}
162

163
/**
164
 * Get currently granted permissions for the user
165
 * @returns List of granted permissions
166
 */
167
function send(method: 'VKWebAppGetGrantedPermissions'): Promise<{
168
  permissions: EGrantedPermission[];
169
}>;
170

171
enum EGrantedPermission {
172
  CAMERA = 'camera',
173
  LOCATION = 'location', 
174
  PHOTO = 'photo'
175
}
176
```
177

178
**Usage Examples:**
179

180
```typescript
181
// Check scope availability before requesting auth
182
const scopeCheck = await bridge.send('VKWebAppCheckAllowedScopes', {
183
  scopes: 'friends,photos,wall,messages'
184
});
185

186
console.log('Scope availability:');
187
scopeCheck.result.forEach(entry => {
188
  console.log(`${entry.scope}: ${entry.allowed ? 'Available' : 'Not available'}`);
189
});
190

191
// Only request allowed scopes
192
const allowedScopes = scopeCheck.result
193
  .filter(entry => entry.allowed)
194
  .map(entry => entry.scope)
195
  .join(',');
196

197
if (allowedScopes) {
198
  const auth = await bridge.send('VKWebAppGetAuthToken', {
199
    app_id: 51665960,
200
    scope: allowedScopes
201
  });
202
}
203

204
// Check granted permissions
205
const permissions = await bridge.send('VKWebAppGetGrantedPermissions');
206
console.log('Granted permissions:', permissions.permissions);
207

208
// Conditional feature access based on permissions
209
if (permissions.permissions.includes(EGrantedPermission.CAMERA)) {
210
  const qrResult = await bridge.send('VKWebAppOpenCodeReader');
211
}
212

213
if (permissions.permissions.includes(EGrantedPermission.LOCATION)) {
214
  const geoData = await bridge.send('VKWebAppGetGeodata');
215
}
216
```
217

218
### API Method Calling
219

220
Call VK API methods directly using obtained access tokens.
221

222
```typescript { .api }
223
/**
224
 * Call VK API methods with authentication
225
 * @param props.method - VK API method name
226
 * @param props.params - Method parameters including access_token
227
 * @returns API method response data
228
 */
229
function send(method: 'VKWebAppCallAPIMethod', props: {
230
  method: string;
231
  params: Record<string, any>;
232
}): Promise<{
233
  response?: any;
234
  error?: {
235
    error_code: number;
236
    error_msg: string;
237
    request_params: Array<{
238
      key: string;
239
      value: string;
240
    }>;
241
  };
242
}>;
243
```
244

245
**Usage Examples:**
246

247
```typescript
248
// Call API method with user token
249
const userToken = 'your_user_access_token';
250
const apiResult = await bridge.send('VKWebAppCallAPIMethod', {
251
  method: 'users.get',
252
  params: {
253
    access_token: userToken,
254
    user_ids: '1,2,3',
255
    fields: 'photo_100,city',
256
    v: '5.131'
257
  }
258
});
259

260
// Call API method with community token
261
const communityToken = 'your_community_access_token';
262
const communityMembers = await bridge.send('VKWebAppCallAPIMethod', {
263
  method: 'groups.getMembers',
264
  params: {
265
    access_token: communityToken,
266
    group_id: '123456789',
267
    count: 1000,
268
    v: '5.131'
269
  }
270
});
271

272
// Handle API errors
273
try {
274
  const result = await bridge.send('VKWebAppCallAPIMethod', {
275
    method: 'wall.post',
276
    params: {
277
      access_token: userToken,
278
      message: 'Hello VK!',
279
      v: '5.131'
280
    }
281
  });
282
  
283
  if (result.error) {
284
    console.error('API Error:', result.error.error_msg);
285
  } else {
286
    console.log('Post ID:', result.response.post_id);
287
  }
288
} catch (error) {
289
  console.error('Bridge Error:', error);
290
}
291
```
292

293
## Authentication Flow Patterns
294

295
### Standard User Auth Flow
296

297
```typescript
298
// 1. Check scope availability
299
const scopes = 'friends,photos,wall';
300
const scopeCheck = await bridge.send('VKWebAppCheckAllowedScopes', { scopes });
301

302
// 2. Filter available scopes
303
const availableScopes = scopeCheck.result
304
  .filter(entry => entry.allowed)
305
  .map(entry => entry.scope)
306
  .join(',');
307

308
// 3. Request authentication
309
if (availableScopes) {
310
  try {
311
    const auth = await bridge.send('VKWebAppGetAuthToken', {
312
      app_id: YOUR_APP_ID,
313
      scope: availableScopes
314
    });
315
    
316
    // 4. Store token securely
317
    localStorage.setItem('vk_access_token', auth.access_token);
318
    localStorage.setItem('vk_token_expires', String(Date.now() + (auth.expires || 3600) * 1000));
319
    
320
    // 5. Use token for API calls
321
    return auth.access_token;
322
  } catch (error) {
323
    console.error('Authentication failed:', error);
324
    throw error;
325
  }
326
} else {
327
  throw new Error('No scopes available for authentication');
328
}
329
```
330

331
### Community Management Flow
332

333
```typescript
334
// 1. Get community token
335
const communityToken = await bridge.send('VKWebAppGetCommunityToken', {
336
  app_id: YOUR_APP_ID,
337
  group_id: COMMUNITY_ID,
338
  scope: 'manage,photos,messages'
339
});
340

341
// 2. Verify community access
342
const communityInfo = await bridge.send('VKWebAppCallAPIMethod', {
343
  method: 'groups.getById',
344
  params: {
345
    access_token: communityToken.access_token,
346
    group_id: String(COMMUNITY_ID),
347
    fields: 'members_count,activity',
348
    v: '5.131'
349
  }
350
});
351

352
// 3. Perform community operations
353
if (communityInfo.response) {
354
  const community = communityInfo.response[0];
355
  console.log(`Managing community: ${community.name} (${community.members_count} members)`);
356
  
357
  // Post content, manage photos, etc.
358
}
359
```
360

361
## Error Handling
362

363
```typescript
364
try {
365
  const auth = await bridge.send('VKWebAppGetAuthToken', {
366
    app_id: 51665960,
367
    scope: 'friends,photos'
368
  });
369
} catch (error) {
370
  if (error.error_type === 'auth_error') {
371
    switch (error.error_data.error_code) {
372
      case 4: // User cancelled authorization
373
        console.log('User cancelled authorization');
374
        break;
375
      case 5: // User denied permission
376
        console.log('User denied permission');
377
        break;
378
      default:
379
        console.error('Authentication error:', error.error_data.error_reason);
380
    }
381
  } else {
382
    console.error('Unexpected error:', error);
383
  }
384
}
385
```