0
# Authentication & Teams
1

2
Authentication management and team switching functionality for multi-account workflows, secure login, and team collaboration features.
3

4
## Capabilities
5

6
### User Authentication
7

8
Secure authentication with Netlify using OAuth-based login system.
9

10
```typescript { .api }
11
/**
12
 * Login to Netlify account
13
 * Command: netlify login [options]
14
 */
15
interface LoginOptions {
16
  /** Login to new Netlify account (switches accounts) */
17
  new?: boolean;
18
}
19

20
/**
21
 * Logout from Netlify account
22
 * Command: netlify logout
23
 */
24
interface LogoutOptions {
25
  /** No additional options for logout */
26
}
27
```
28

29
**Usage Examples:**
30

31
```bash
32
# Login with browser-based OAuth
33
netlify login
34

35
# Login to a different account
36
netlify login --new
37

38
# Logout from current account
39
netlify logout
40
```
41

42
### Authentication Flow
43

44
OAuth-based authentication process and token management:
45

46
```typescript { .api }
47
/**
48
 * Authentication flow configuration
49
 */
50
interface AuthenticationFlow {
51
  /** OAuth configuration */
52
  oauth: {
53
    /** Authorization URL */
54
    authUrl: 'https://app.netlify.com/authorize';
55
    /** Token endpoint */
56
    tokenUrl: 'https://api.netlify.com/oauth/token';
57
    /** Client ID for CLI application */
58
    clientId: string;
59
    /** Required scopes */
60
    scopes: ['api', 'site:read', 'site:write'];
61
    /** Redirect URI for localhost callback */
62
    redirectUri: 'http://localhost:8080/callback';
63
  };
64
  
65
  /** Browser authentication */
66
  browserAuth: {
67
    /** Opens browser for authentication */
68
    openBrowser: boolean;
69
    /** Localhost server for callback */
70
    callbackServer: {
71
      port: number;
72
      timeout: number; // milliseconds
73
    };
74
    /** Fallback for headless environments */
75
    manualToken: boolean;
76
  };
77
  
78
  /** Token storage */
79
  tokenStorage: {
80
    /** Token storage location */
81
    location: '~/.netlify/config.json';
82
    /** Token encryption */
83
    encrypted: boolean;
84
    /** Token expiration */
85
    expiresIn: number; // seconds
86
    /** Refresh token support */
87
    refreshToken: boolean;
88
  };
89
}
90
```
91

92
### User Information and Profile
93

94
Access current user information and profile data:
95

96
```typescript { .api }
97
/**
98
 * Current user information
99
 */
100
interface UserProfile {
101
  /** User ID */
102
  id: string;
103
  /** Display name */
104
  name: string;
105
  /** Email address */
106
  email: string;
107
  /** Avatar URL */
108
  avatarUrl: string;
109
  /** Account creation date */
110
  createdAt: Date;
111
  /** Last activity timestamp */
112
  lastActiveAt: Date;
113
  /** Account verification status */
114
  verified: boolean;
115
  /** Two-factor authentication enabled */
116
  twoFactorEnabled: boolean;
117
  /** Account plan */
118
  plan: 'starter' | 'pro' | 'business' | 'enterprise';
119
  /** Account limits */
120
  limits: {
121
    sites: number;
122
    bandwidth: number; // bytes per month
123
    buildMinutes: number; // minutes per month
124
    functions: {
125
      invocations: number; // per month
126
      runtime: number; // seconds per month
127
    };
128
  };
129
}
130
```
131

132
### Team Management
133

134
Handle multi-team workflows and team switching:
135

136
```typescript { .api }
137
/**
138
 * Switch between teams/accounts
139
 * Command: netlify switch
140
 */
141
interface SwitchTeamOptions {
142
  /** No additional options - interactive selection */
143
}
144

145
/**
146
 * Team information structure
147
 */
148
interface TeamInfo {
149
  /** Team ID */
150
  id: string;
151
  /** Team name */
152
  name: string;
153
  /** Team slug (URL identifier) */
154
  slug: string;
155
  /** User's role in the team */
156
  role: 'owner' | 'collaborator' | 'developer' | 'viewer';
157
  /** Team plan */
158
  plan: {
159
    type: 'starter' | 'pro' | 'business' | 'enterprise';
160
    features: string[];
161
    limits: {
162
      sites: number;
163
      members: number;
164
      bandwidth: number;
165
      buildMinutes: number;
166
    };
167
  };
168
  /** Team statistics */
169
  stats: {
170
    memberCount: number;
171
    siteCount: number;
172
    totalBandwidth: number;
173
    buildMinutesUsed: number;
174
  };
175
  /** Team settings */
176
  settings: {
177
    billingEmail: string;
178
    defaultDomain: string;
179
    customBranding: boolean;
180
    ssoEnabled: boolean;
181
    ipRestrictions: string[];
182
  };
183
  /** Team creation date */
184
  createdAt: Date;
185
  /** Team owner information */
186
  owner: {
187
    id: string;
188
    name: string;
189
    email: string;
190
  };
191
}
192
```
193

194
**Usage Examples:**
195

196
```bash
197
# Interactive team switching
198
netlify switch
199

200
# This will show a list like:
201
# ? Switch to which team? (Use arrow keys)
202
# ❯ Personal Account (john@example.com)
203
#   Acme Corp (acme-corp)
204
#   Startup Inc (startup-inc)
205
```
206

207
### Team Member Management
208

209
Team member roles and permissions system:
210

211
```typescript { .api }
212
/**
213
 * Team member roles and permissions
214
 */
215
interface TeamMember {
216
  /** Member ID */
217
  id: string;
218
  /** Member information */
219
  user: {
220
    name: string;
221
    email: string;
222
    avatarUrl: string;
223
  };
224
  /** Member role */
225
  role: TeamRole;
226
  /** Join date */
227
  joinedAt: Date;
228
  /** Last activity */
229
  lastActiveAt: Date;
230
  /** Invitation status */
231
  status: 'active' | 'pending' | 'suspended';
232
}
233

234
/**
235
 * Team role definitions
236
 */
237
type TeamRole = 'owner' | 'collaborator' | 'developer' | 'viewer';
238

239
interface TeamRolePermissions {
240
  owner: {
241
    sites: ['create', 'read', 'update', 'delete', 'deploy'];
242
    team: ['invite', 'remove', 'change-roles', 'billing', 'settings'];
243
    functions: ['create', 'read', 'update', 'delete', 'invoke'];
244
    environment: ['read', 'write', 'delete'];
245
    builds: ['trigger', 'cancel', 'view-logs'];
246
  };
247
  
248
  collaborator: {
249
    sites: ['create', 'read', 'update', 'deploy'];
250
    team: ['invite'];
251
    functions: ['create', 'read', 'update', 'delete', 'invoke'];
252
    environment: ['read', 'write'];
253
    builds: ['trigger', 'view-logs'];
254
  };
255
  
256
  developer: {
257
    sites: ['read', 'deploy'];
258
    team: [];
259
    functions: ['read', 'invoke'];
260
    environment: ['read'];
261
    builds: ['trigger', 'view-logs'];
262
  };
263
  
264
  viewer: {
265
    sites: ['read'];
266
    team: [];
267
    functions: ['read'];
268
    environment: ['read'];
269
    builds: ['view-logs'];
270
  };
271
}
272
```
273

274
### Authentication State Management
275

276
Current authentication state and session management:
277

278
```typescript { .api }
279
/**
280
 * Authentication state information
281
 */
282
interface AuthState {
283
  /** Whether user is authenticated */
284
  isAuthenticated: boolean;
285
  /** Current user information */
286
  user?: UserProfile;
287
  /** Current team context */
288
  currentTeam?: TeamInfo;
289
  /** Available teams */
290
  availableTeams: TeamInfo[];
291
  /** Authentication token info */
292
  token: {
293
    value: string;
294
    expiresAt: Date;
295
    scopes: string[];
296
    type: 'Bearer';
297
  };
298
  /** Session information */
299
  session: {
300
    startedAt: Date;
301
    lastActivity: Date;
302
    ipAddress: string;
303
    userAgent: string;
304
  };
305
}
306

307
/**
308
 * Authentication status check
309
 */
310
interface AuthStatusCheck {
311
  /** Check if token is valid */
312
  isValidToken: boolean;
313
  /** Check if token is expired */
314
  isExpired: boolean;
315
  /** Time until expiration */
316
  expiresIn: number; // seconds
317
  /** Whether refresh is needed */
318
  needsRefresh: boolean;
319
  /** Last authentication check */
320
  lastCheck: Date;
321
}
322
```
323

324
### Security Features
325

326
Security settings and features for account protection:
327

328
```typescript { .api }
329
/**
330
 * Account security configuration
331
 */
332
interface SecurityConfig {
333
  /** Two-factor authentication */
334
  twoFactor: {
335
    enabled: boolean;
336
    method: 'app' | 'sms' | 'email';
337
    backupCodes: number;
338
    lastUsed: Date;
339
  };
340
  
341
  /** Login security */
342
  loginSecurity: {
343
    /** Failed login attempts */
344
    failedAttempts: number;
345
    /** Account lockout settings */
346
    lockout: {
347
      enabled: boolean;
348
      threshold: number;
349
      duration: number; // minutes
350
    };
351
    /** IP restrictions */
352
    ipRestrictions: {
353
      enabled: boolean;
354
      allowedIps: string[];
355
    };
356
  };
357
  
358
  /** Session management */
359
  sessionManagement: {
360
    /** Maximum concurrent sessions */
361
    maxSessions: number;
362
    /** Session timeout */
363
    timeout: number; // minutes
364
    /** Remember me option */
365
    rememberMe: boolean;
366
    /** Force logout on IP change */
367
    forceLogoutOnIpChange: boolean;
368
  };
369
  
370
  /** API access */
371
  apiAccess: {
372
    /** Personal access tokens */
373
    personalTokens: Array<{
374
      id: string;
375
      name: string;
376
      scopes: string[];
377
      createdAt: Date;
378
      lastUsed: Date;
379
      expiresAt?: Date;
380
    }>;
381
    /** OAuth applications */
382
    oauthApps: Array<{
383
      id: string;
384
      name: string;
385
      permissions: string[];
386
      authorizedAt: Date;
387
    }>;
388
  };
389
}
390
```
391

392
### Single Sign-On (SSO) Integration
393

394
Enterprise SSO features and configuration:
395

396
```typescript { .api }
397
/**
398
 * SSO configuration for enterprise teams
399
 */
400
interface SSOConfig {
401
  /** SSO provider */
402
  provider: 'saml' | 'oidc' | 'google' | 'github' | 'gitlab';
403
  
404
  /** SAML configuration */
405
  saml?: {
406
    entityId: string;
407
    ssoUrl: string;
408
    x509Certificate: string;
409
    signAssertions: boolean;
410
    signRequests: boolean;
411
  };
412
  
413
  /** OIDC configuration */
414
  oidc?: {
415
    issuer: string;
416
    clientId: string;
417
    clientSecret: string;
418
    scopes: string[];
419
    userInfoEndpoint: string;
420
  };
421
  
422
  /** User provisioning */
423
  provisioning: {
424
    /** Automatic user creation */
425
    autoProvision: boolean;
426
    /** Default role for new users */
427
    defaultRole: TeamRole;
428
    /** Attribute mapping */
429
    attributeMapping: {
430
      email: string;
431
      name: string;
432
      role?: string;
433
    };
434
  };
435
  
436
  /** SSO enforcement */
437
  enforcement: {
438
    /** Require SSO for all team members */
439
    required: boolean;
440
    /** Grace period for existing users */
441
    gracePeriod: number; // days
442
    /** Allowed non-SSO users */
443
    exceptions: string[]; // email addresses
444
  };
445
}
446
```
447

448
### CLI Configuration Management
449

450
CLI-specific configuration and preferences:
451

452
```typescript { .api }
453
/**
454
 * CLI configuration settings
455
 */
456
interface CLIConfig {
457
  /** User preferences */
458
  preferences: {
459
    /** Default output format */
460
    defaultFormat: 'table' | 'json' | 'yaml';
461
    /** Color output */
462
    colorOutput: boolean;
463
    /** Telemetry settings */
464
    telemetry: {
465
      enabled: boolean;
466
      anonymizeIps: boolean;
467
      shareUsageStats: boolean;
468
    };
469
    /** Update notifications */
470
    updateNotifications: boolean;
471
  };
472
  
473
  /** Default values */
474
  defaults: {
475
    /** Default team/account */
476
    defaultTeam?: string;
477
    /** Default deploy context */
478
    defaultContext: 'production' | 'deploy-preview' | 'branch-deploy' | 'dev';
479
    /** Default functions directory */
480
    functionsDir: string;
481
    /** Default publish directory */
482
    publishDir: string;
483
  };
484
  
485
  /** Alias and shortcuts */
486
  aliases: Record<string, string>;
487
  
488
  /** Plugin configuration */
489
  plugins: Array<{
490
    name: string;
491
    version: string;
492
    enabled: boolean;
493
    config: Record<string, any>;
494
  }>;
495
}
496
```