---
title: 'Authentication'
description: 'Learn how to authenticate with the WinkSocial API'
---

# Authentication

The WinkSocial API uses Bearer token authentication for all requests. This guide explains how to obtain and use your API keys.

## 🔑 API Keys

### Getting Your API Key

1. **Admin Access Required**: Only admin users can generate API keys
2. **Navigate to Settings**: Go to **Settings** → **API Keys** in your admin panel
3. **Generate Key**: Click "Generate New API Key"
4. **Copy Key**: Copy the generated key immediately (it won't be shown again)
5. **Store Securely**: Keep your API key secure and never share it publicly

### API Key Format

API keys are 64-character hexadecimal strings:

```
Bearer 8f7d9e6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8
```

## 🔐 Using API Keys

### HTTP Headers

Include your API key in the `Authorization` header of every request:

```bash
curl -X GET "https://api.joinwink.app/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### JavaScript/TypeScript

```typescript
const response = await fetch('https://api.joinwink.app/v1/users', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
```

### React Native

```javascript
const response = await fetch('https://api.joinwink.app/v1/users', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
```

## 🚨 Security Best Practices

### Keep Keys Secure
- **Never commit** API keys to version control
- **Use environment variables** for local development
- **Rotate keys regularly** (every 90 days recommended)
- **Monitor usage** for suspicious activity

### Environment Variables

```bash
# .env file
WINKSOCIAL_API_KEY=your_api_key_here
```

```javascript
// Usage
const apiKey = process.env.WINKSOCIAL_API_KEY;
```

### Key Rotation

1. **Generate New Key**: Create a new API key in admin panel
2. **Update Applications**: Update all applications with new key
3. **Test New Key**: Verify new key works correctly
4. **Delete Old Key**: Remove old key from admin panel
5. **Monitor**: Watch for any failed requests

## 📊 Rate Limiting

### Limits by Plan

| Plan | Requests/Hour | Burst Limit |
|------|---------------|-------------|
| Standard | 1,000 | 100 |
| Premium | 5,000 | 500 |
| Enterprise | 20,000 | 2,000 |

### Rate Limit Headers

Response headers include rate limit information:

```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```

### Handling Rate Limits

When you hit rate limits, you'll receive a `429 Too Many Requests` response:

```json
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 3600 seconds.",
  "retry_after": 3600
}
```

## 🔍 Testing Authentication

### Test Endpoint

Use our test endpoint to verify your API key:

```bash
curl -X GET "https://api.joinwink.app/v1/auth/test" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Success Response

```json
{
  "success": true,
  "message": "Authentication successful",
  "user": {
    "id": "admin_user_id",
    "email": "admin@winksocial.com",
    "role": "admin",
    "permissions": ["read", "write", "admin"]
  }
}
```

### Error Response

```json
{
  "error": "unauthorized",
  "message": "Invalid or missing API key",
  "code": 401
}
```

## 🛠️ SDK Authentication

### JavaScript SDK

```javascript
import { WinkSocialAPI } from '@winksocial/js-sdk';

const api = new WinkSocialAPI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.joinwink.app/v1'
});

// Test connection
const user = await api.auth.test();
```

### React Native SDK

```javascript
import { WinkSocialAPI } from '@winksocial/react-native-sdk';

const api = new WinkSocialAPI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.joinwink.app/v1'
});

// Test connection
const user = await api.auth.test();
```

## 🚫 Common Issues

### Invalid API Key

```json
{
  "error": "unauthorized",
  "message": "Invalid API key",
  "code": 401
}
```

**Solutions:**
- Verify API key is correct
- Check for extra spaces or characters
- Ensure key hasn't expired
- Confirm admin permissions

### Missing API Key

```json
{
  "error": "unauthorized",
  "message": "Missing API key",
  "code": 401
}
```

**Solutions:**
- Include `Authorization` header
- Use correct format: `Bearer YOUR_KEY`
- Check request headers

### Expired API Key

```json
{
  "error": "unauthorized",
  "message": "API key expired",
  "code": 401
}
```

**Solutions:**
- Generate new API key
- Update applications
- Check key expiration date

## 📞 Support

Need help with authentication?

- **Email**: hello@joinwink.app
- **Admin Panel**: Check API key status
- **Documentation**: This guide
- **Community**: Developer forums

---

Next: Learn about [error handling](/errors) or explore the [API reference](/api-reference/users).