🌟 Overview
All Sports Buddies API requests require authentication to ensure security and proper access control. We support two main authentication methods:
- OAuth 2.0 - Recommended for user-facing applications
- API Keys - Suitable for server-to-server integrations
💡 Best Practice
Use OAuth 2.0 for applications that interact with user data, and API keys for backend services and integrations.
🔄 OAuth 2.0 Flow
OAuth 2.0 is the recommended authentication method for applications that need to access user data on behalf of Sports Buddies users.
Authorization Code Flow
This is the most secure OAuth flow and is recommended for web applications:
- Redirect User: Redirect users to our authorization endpoint
- User Authorization: User grants permission to your application
- Authorization Code: We redirect back with an authorization code
- Exchange for Tokens: Exchange the code for access and refresh tokens
- Make API Calls: Use the access token for API requests
Step 1: Redirect to Authorization Endpoint
https://api.joinsportsbuddies.app/oauth/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=YOUR_REDIRECT_URI&
response_type=code&
scope=read write&
state=RANDOM_STATE_STRING
Step 2: Exchange Authorization Code for Tokens
POST https://api.joinsportsbuddies.app/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REDIRECT_URI
Step 3: Token Response
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "def50200...",
"scope": "read write"
}
🔑 API Keys
API keys are suitable for server-to-server integrations and applications that don't require user-specific data access.
⚠️ Security Warning
Keep your API keys secure and never expose them in client-side code or public repositories. API keys should be treated like passwords.
Using API Keys
Include your API key in the Authorization header of your requests:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request Example
curl -X GET "https://api.joinsportsbuddies.app/v1/users/me" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
🎯 OAuth Scopes
Scopes define the level of access your application has to user data and platform features.
| Scope |
Description |
Access Level |
read |
Read access to user profile and public data |
Basic |
write |
Create and update user data, send messages |
Standard |
profile |
Full access to user profile information |
Enhanced |
matching |
Access to matching algorithm and recommendations |
Enhanced |
events |
Create and manage events and activities |
Enhanced |
admin |
Administrative access (enterprise only) |
Enterprise |
🔄 Token Management
Proper token management is crucial for maintaining secure API access.
Access Token Expiration
Access tokens expire after 1 hour (3600 seconds) for security reasons. You should:
- Store tokens securely
- Monitor token expiration
- Use refresh tokens to get new access tokens
- Handle token refresh errors gracefully
Refreshing Access Tokens
POST https://api.joinsportsbuddies.app/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
refresh_token=YOUR_REFRESH_TOKEN
Token Refresh Response
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "def50200...",
"scope": "read write"
}
❌ Error Handling
Proper error handling ensures your application can respond appropriately to authentication failures.
Common Authentication Errors
| Error Code |
Description |
Solution |
invalid_client |
Invalid client ID or secret |
Check your credentials |
invalid_grant |
Invalid authorization code or refresh token |
Request new authorization |
invalid_scope |
Requested scope is invalid |
Check scope values |
unauthorized_client |
Client not authorized for requested grant type |
Contact support |
access_denied |
User denied authorization |
Handle gracefully |
Error Response Format
{
"error": "invalid_grant",
"error_description": "The authorization code has expired",
"error_uri": "https://docs.joinsportsbuddies.app/api/errors"
}
🛡️ Security Best Practices
Follow these security guidelines to protect your application and users.
Token Security
- Store Securely: Use secure storage methods (keychain, encrypted databases)
- Transmit Securely: Always use HTTPS for API calls
- Rotate Regularly: Implement token rotation for long-lived applications
- Monitor Usage: Track token usage for suspicious activity
Client Security
- Protect Secrets: Never expose client secrets in client-side code
- Validate Redirects: Always validate redirect URIs
- Use State Parameter: Implement CSRF protection with state parameter
- Limit Scopes: Request only the scopes you actually need
User Privacy
- Minimal Data: Only request access to data you need
- User Consent: Clearly explain what data you'll access
- Data Retention: Don't store user data longer than necessary
- User Control: Provide users with data access controls
💻 Implementation Examples
Here are complete examples for different programming languages and platforms.
JavaScript (Node.js)
const axios = require('axios');
class SportsBuddiesAPI {
constructor(clientId, clientSecret) {
this.clientId = clientId;
this.clientSecret = clientSecret;
this.baseURL = 'https://api.joinsportsbuddies.app';
}
async getAccessToken(authorizationCode, redirectUri) {
const response = await axios.post(`${this.baseURL}/oauth/token`, {
grant_type: 'authorization_code',
client_id: this.clientId,
client_secret: this.clientSecret,
code: authorizationCode,
redirect_uri: redirectUri
});
return response.data.access_token;
}
async makeAuthenticatedRequest(endpoint, accessToken) {
const response = await axios.get(`${this.baseURL}${endpoint}`, {
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
}
});
return response.data;
}
}
// Usage
const api = new SportsBuddiesAPI('your_client_id', 'your_client_secret');
Python
import requests
class SportsBuddiesAPI:
def __init__(self, client_id, client_secret):
self.client_id = client_id
self.client_secret = client_secret
self.base_url = 'https://api.joinsportsbuddies.app'
def get_access_token(self, authorization_code, redirect_uri):
response = requests.post(f'{self.base_url}/oauth/token', data={
'grant_type': 'authorization_code',
'client_id': self.client_id,
'client_secret': self.client_secret,
'code': authorization_code,
'redirect_uri': redirect_uri
})
return response.json()['access_token']
def make_authenticated_request(self, endpoint, access_token):
headers = {
'Authorization': f'Bearer {access_token}',
'Content-Type': 'application/json'
}
response = requests.get(f'{self.base_url}{endpoint}', headers=headers)
return response.json()
# Usage
api = SportsBuddiesAPI('your_client_id', 'your_client_secret')
🧪 Testing & Development
Tools and tips for testing your authentication implementation.
Test Credentials
For development and testing, you can use our sandbox environment:
- Sandbox URL:
https://sandbox-api.joinsportsbuddies.app
- Test Client ID: Available in developer portal
- Test Users: Pre-created test accounts
- Rate Limits: Higher limits for testing
Testing Tools
- Postman: API testing and documentation
- cURL: Command-line testing
- OAuth Playground: Interactive OAuth testing
- JWT Debugger: Token inspection and validation
🆘 Support & Resources
Get help with authentication and access additional resources.
Getting Help