0
# Authentication
1

2
Authentication and initialization functionality for accessing the Roboflow platform. This includes API key validation, workspace configuration, and CLI-based login flows.
3

4
## Capabilities
5

6
### Roboflow Client Class
7

8
The main entry point for the Roboflow SDK that handles authentication and provides access to workspaces and projects.
9

10
```python { .api }
11
class Roboflow:
12
    def __init__(self, api_key=None, model_format="undefined", notebook="undefined"):
13
        """
14
        Initialize Roboflow client with API credentials.
15
        
16
        Parameters:
17
        - api_key: str, optional - Your Roboflow API key. If not provided, loads from environment or config
18
        - model_format: str - Model format preference for downloads (default: "undefined")
19
        - notebook: str - Notebook environment identifier (default: "undefined")
20
        """
21
    
22
    def workspace(self, the_workspace=None):
23
        """
24
        Access a workspace.
25
        
26
        Parameters:
27
        - the_workspace: str, optional - Workspace name/ID. Uses default if not specified
28
        
29
        Returns:
30
        Workspace object for the specified workspace
31
        """
32
    
33
    def project(self, project_name, the_workspace=None):
34
        """
35
        Access a project directly without going through workspace.
36
        
37
        Parameters:
38
        - project_name: str - Name of the project or "workspace/project" format
39
        - the_workspace: str, optional - Workspace name if not in project_name
40
        
41
        Returns:
42
        Project object for the specified project
43
        """
44
```
45

46
### CLI Authentication
47

48
Functions for authenticating via command line interface and configuring persistent access.
49

50
```python { .api }
51
def login(workspace=None, force=False):
52
    """
53
    Authenticate via CLI with interactive token entry.
54
    
55
    Parameters:
56
    - workspace: str, optional - Specific workspace to authenticate for
57
    - force: bool - Force re-authentication even if already logged in
58
    
59
    Returns:
60
    None - Saves authentication to config file
61
    """
62
```
63

64
### High-Level Initialization
65

66
Convenience function for initializing workspace access.
67

68
```python { .api }
69
def initialize_roboflow(the_workspace=None):
70
    """
71
    High-level function to initialize Roboflow workspace.
72
    
73
    Parameters:
74
    - the_workspace: str, optional - Workspace URL/name to initialize
75
    
76
    Returns:
77
    Workspace object for the initialized workspace
78
    """
79
```
80

81
### API Key Validation
82

83
Internal function for validating API keys with the Roboflow server.
84

85
```python { .api }
86
def check_key(api_key, model, notebook, num_retries=0):
87
    """
88
    Validates API key with Roboflow server.
89
    
90
    Parameters:
91
    - api_key: str - The API key to validate
92
    - model: str - Model format context
93
    - notebook: str - Notebook environment context  
94
    - num_retries: int - Number of retry attempts on failure
95
    
96
    Returns:
97
    dict or str - Validation response or "onboarding" for demo keys
98
    
99
    Raises:
100
    RuntimeError - If API key is invalid or server validation fails
101
    """
102
```
103

104
## Usage Examples
105

106
### Basic Authentication
107

108
```python
109
import roboflow
110

111
# Authenticate with API key
112
rf = roboflow.Roboflow(api_key="your_api_key_here")
113

114
# Or use environment variable/config file
115
rf = roboflow.Roboflow()  # Loads from ROBOFLOW_API_KEY env var or config
116
```
117

118
### CLI Authentication
119

120
```python
121
import roboflow
122

123
# Interactive CLI login
124
roboflow.login()
125

126
# Force re-authentication
127
roboflow.login(force=True)
128

129
# Login for specific workspace
130
roboflow.login(workspace="my-workspace")
131
```
132

133
### Workspace Access Patterns
134

135
```python
136
# Access default workspace
137
workspace = rf.workspace()
138

139
# Access specific workspace
140
workspace = rf.workspace("my-workspace-name")
141

142
# Direct project access
143
project = rf.project("my-project")
144

145
# Project with specific workspace
146
project = rf.project("my-project", "my-workspace")
147
```
148

149
## Configuration
150

151
The SDK supports multiple authentication methods:
152

153
1. **API Key Parameter**: Pass directly to `Roboflow()` constructor
154
2. **Environment Variable**: Set `ROBOFLOW_API_KEY` environment variable
155
3. **Config File**: Use `roboflow.login()` to save authentication token
156
4. **Demo Keys**: Built-in demo keys for public dataset access
157

158
Config files are stored at:
159
- **Linux/macOS**: `~/.config/roboflow/config.json`
160
- **Windows**: `%USERPROFILE%/roboflow/config.json`
161

162
## Error Handling
163

164
Authentication failures raise `RuntimeError` with descriptive messages. Common scenarios:
165

166
```python
167
try:
168
    rf = roboflow.Roboflow(api_key="invalid_key")
169
    workspace = rf.workspace()
170
except RuntimeError as e:
171
    print(f"Authentication failed: {e}")
172
```