Authentication
Authentication
Complete guide to authenticating with the Synoveo API
The Synoveo API uses different authentication methods depending on your use case. All API requests require authentication via Bearer tokens.
Authentication Methods
| Method | Token Scope | Use Case | TTL |
|---|---|---|---|
| Google OAuth | user | Dashboard, web applications | 7 days |
| API Keys | service | WordPress plugin, integrations | 90 days |
| Service Clients | service | Custom server-to-server | 90 days |
Google OAuth
Connect Google Business Profile accounts
API Keys
Generate credentials for integrations
Service Clients
OAuth2 client credentials flow
JWT Tokens
Token structure and validation
Quick Start
Step 1: Get Credentials
Create an API key from your Dashboard:
- Navigate to Developer → API Keys
- Click Create API Key
- Select the Location to connect
- Copy your
client_idandclient_secret
Important: The client secret is only shown once. Store it securely.
Step 2: Exchange for Token
curl -X POST https://api.synoveo.com/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "syncid_570_1703030400000_my_app",
"client_secret": "your_base64_secret"
}'Response:
{
"status": "ok",
"data": {
"token_type": "Bearer",
"scope": "service",
"plan": "pro",
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 7776000,
"permissions": ["business.read", "business.write"],
"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}Step 3: Use the Token
Include the token in the Authorization header:
curl https://api.synoveo.com/api/v1/google-business/locations \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."Token Expiration
| Token Type | Default TTL | Environment Variable |
|---|---|---|
| Access Token | 90 days | JWT_SERVICE_TTL_SECONDS |
| Refresh Token | 30 days | REFRESH_TTL_SECONDS |
| User Token (Dashboard) | 7 days | - |
Refreshing Tokens
When your access token expires, use the refresh token to get a new one:
curl -X POST https://api.synoveo.com/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "refresh_token",
"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}'Permissions
Service tokens can request specific permissions:
| Permission | Description |
|---|---|
business.read | Read business profile, locations, reviews |
business.write | Update profile, create posts, sync data |
Request specific permissions during token exchange:
{
"grant_type": "client_credentials",
"client_id": "syncid_570_...",
"client_secret": "...",
"permissions": ["business.read"]
}The returned permissions are the intersection of requested and allowed permissions.
Error Responses
| Error Code | Status | Description |
|---|---|---|
AUTH_INVALID_TOKEN | 401 | Invalid or expired token |
AUTH_MISSING_TOKEN | 401 | No Authorization header |
AUTH_TOKEN_EXPIRED | 401 | Token has expired |
AUTH_INSUFFICIENT_PERMISSIONS | 403 | Missing required permission |
{
"status": "error",
"error": {
"code": "AUTH_INVALID_TOKEN",
"message": "The provided token is invalid or has expired"
}
}Security Best Practices
- Never expose secrets - Store
client_secretin environment variables - Use HTTPS - All API requests must use HTTPS
- Rotate keys - Periodically rotate API keys in production
- Scope appropriately - Request only needed permissions
- Cache tokens - Don't request new tokens for every API call