SDK Token Management
SDK tokens are long-lived refresh tokens that enable automatic authentication for your SDK. Unlike API keys, SDK tokens automatically rotate for enhanced security and support OAuth 2.0 refresh flows. Monitor active tokens, revoke compromised tokens, and maintain security compliance from a centralized interface.
Auto-Rotation: SDK tokens automatically refresh before expiration. Your SDK handles this transparently - you never need to manually update tokens.
Token Lifecycle
Generation
Created automatically when you download an SDK. Each download generates a new refresh token with a 30-day lifetime.
Auto-Refresh
SDK automatically exchanges refresh tokens for access tokens. Refresh tokens rotate on each use for security.
Expiration
Access tokens expire in 1 hour. Refresh tokens expire in 30 days but are renewed with each successful refresh.
Revocation
Immediately revoke compromised tokens. Revocation affects all tokens in the chain, preventing further refreshes.
Token Management API
List Your SDK Tokens
curl -X GET https://api.opena2a.org/v1/users/me/sdk-tokens \
-H "Authorization: Bearer YOUR_TOKEN"{
"tokens": [
{
"id": "sdk_9kL4n6oZ0rN5sT8v",
"name": "Python SDK - MacBook Pro",
"created_at": "2024-01-01T10:00:00Z",
"last_used": "2024-01-15T14:30:00Z",
"expires_at": "2024-01-31T10:00:00Z",
"status": "active",
"refresh_count": 14,
"device_info": {
"platform": "darwin",
"hostname": "MacBook-Pro.local",
"sdk_version": "1.2.0"
}
},
{
"id": "sdk_7hJ3m5nY8qM4pS6u",
"name": "Python SDK - Ubuntu Server",
"created_at": "2023-12-15T08:00:00Z",
"last_used": "2024-01-14T22:15:00Z",
"expires_at": "2024-01-14T08:00:00Z",
"status": "expired",
"refresh_count": 28,
"device_info": {
"platform": "linux",
"hostname": "prod-server-01",
"sdk_version": "1.1.8"
}
}
],
"total": 2,
"active": 1,
"expired": 1
}Get Active Token Count
curl -X GET https://api.opena2a.org/v1/users/me/sdk-tokens/count \
-H "Authorization: Bearer YOUR_TOKEN"Revoke a Token
Warning: Revoking a token immediately invalidates it and all tokens derived from it. Any SDK using this token will stop working immediately.
curl -X POST https://api.opena2a.org/v1/users/me/sdk-tokens/sdk_9kL4n6oZ0rN5sT8v/revoke \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"reason": "Compromised device",
"notify": true
}'Revoke All Tokens
Danger: This will revoke ALL your SDK tokens. All SDKs will stop working and you'll need to download and redistribute new SDKs to all installations.
curl -X POST https://api.opena2a.org/v1/users/me/sdk-tokens/revoke-all \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"confirm": true,
"reason": "Security audit requirement"
}'Token Security
Security Best Practices
- • Regular Audits: Review active tokens monthly and revoke unused ones
- • Device Tracking: Monitor which devices are using your tokens
- • Immediate Revocation: Revoke tokens immediately if a device is compromised
- • Rotation Schedule: Force rotation every 90 days for high-security environments
- • Access Logs: Monitor token usage patterns for anomalies
- • Secure Storage: SDK stores tokens in system keyring, never in plaintext
Token Refresh Flow
Understanding how SDK tokens refresh helps troubleshoot authentication issues:
# OAuth 2.0 Refresh Token Flow
1. SDK detects access token expiration (1 hour)
↓
2. SDK sends refresh token to /auth/refresh endpoint
POST /v1/auth/refresh
{
"refresh_token": "sdk_9kL4n6oZ0rN5sT8v"
}
↓
3. AIM validates refresh token
- Check expiration (30 days)
- Verify not revoked
- Check device fingerprint
↓
4. AIM issues new tokens
{
"access_token": "new_access_token",
"refresh_token": "sdk_NEW_REFRESH_TOKEN", // Rotated!
"expires_in": 3600
}
↓
5. SDK stores new tokens in keyring
↓
6. Old refresh token is invalidated (one-time use)Token Monitoring
Dashboard Alerts: Set up alerts for suspicious token activity like simultaneous usage from different locations or excessive refresh attempts.
Token Usage Metrics
| Metric | Description | Alert Threshold |
|---|---|---|
| Refresh Rate | Refreshes per hour | > 60/hour |
| Geographic Anomaly | Usage from new location | Any new country |
| Concurrent Usage | Same token from multiple IPs | > 2 IPs |
| Failed Refreshes | Consecutive failed attempts | > 5 attempts |
| Token Age | Days since creation | > 90 days |
Troubleshooting
Common Issues
Token Expired (401 Error)
Refresh token has expired after 30 days of inactivity.
Solution: Download a new SDK package.
Token Revoked (403 Error)
Token was manually revoked or flagged for security.
Solution: Check token status and download new SDK if needed.
Too Many Refreshes (429 Error)
Rate limit exceeded for token refresh endpoint.
Solution: Check for refresh loops in your code. Wait before retrying.
Invalid Token Format
Token corrupted or modified.
Solution: Ensure keyring is working properly. Re-download SDK if needed.