Authentication
The SalesOS API uses JWT (JSON Web Tokens) for authentication, powered by Auth0. Every API request must include a valid JWT token in the Authorization header.
Authentication Flow
Obtain a token
Request a JWT token from Auth0 using your credentials or API key.
Include the token in requests
Add the token to the Authorization header of every API request.
Refresh when expired
Tokens expire after a set period. Use the refresh token to obtain a new access token without re-authenticating.
Getting a Token
Option 1: Client Credentials (Machine-to-Machine)
For server-to-server integrations, use the OAuth 2.0 Client Credentials flow:
curl -X POST https://auth.play2sell.com/oauth/token \
-H "Content-Type: application/json" \
-d '{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"audience": "https://api.play2sell.com",
"grant_type": "client_credentials"
}'
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400
}
Option 2: Authorization Code (User-Based)
For applications that act on behalf of a user, use the Authorization Code flow:
- Redirect the user to the Auth0 authorization endpoint:
https://auth.play2sell.com/authorize?
response_type=code&
client_id=YOUR_CLIENT_ID&
redirect_uri=YOUR_CALLBACK_URL&
audience=https://api.play2sell.com&
scope=openid profile email
-
After the user authenticates, Auth0 redirects to your callback URL with a
code parameter.
-
Exchange the code for tokens:
curl -X POST https://auth.play2sell.com/oauth/token \
-H "Content-Type: application/json" \
-d '{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"code": "AUTHORIZATION_CODE",
"redirect_uri": "YOUR_CALLBACK_URL",
"grant_type": "authorization_code"
}'
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "v1.abc123...",
"id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400
}
Using the Token
Include the access token in the Authorization header of every API request:
curl -X GET https://api.play2sell.com/v1/leads \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
Never include tokens in URL query parameters. Always use the Authorization header. Tokens in URLs can be logged by proxies and web servers.
Token Expiration and Refresh
Access tokens expire after 24 hours (86400 seconds). When a token expires, the API returns a 401 Unauthorized response.
Refreshing a Token
If you have a refresh token (from the Authorization Code flow), use it to get a new access token:
curl -X POST https://auth.play2sell.com/oauth/token \
-H "Content-Type: application/json" \
-d '{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"refresh_token": "YOUR_REFRESH_TOKEN",
"grant_type": "refresh_token"
}'
Client Credentials tokens do not have refresh tokens. When a client credentials token expires, simply request a new one using your client ID and secret.
Getting API Credentials
From the Admin Panel
- Go to Admin > Integrations > API Keys
- Click Create API Client
- Name your client (e.g., “CRM Sync”, “Marketing Automation”)
- Select the permissions scope
- Save and copy the
client_id and client_secret
Scopes and Permissions
API clients can be limited to specific scopes:
| Scope | Permissions |
|---|
leads:read | Read lead data |
leads:write | Create and update leads |
deals:read | Read deal data |
deals:write | Create and update deals |
users:read | Read user data |
users:write | Manage users |
reports:read | Access reports and dashboards |
webhooks:manage | Create and manage webhooks |
Follow the principle of least privilege. Only grant the scopes your integration actually needs. You can always add more scopes later.
Security Best Practices
- Store secrets securely — Never hardcode client secrets in source code. Use environment variables or a secrets manager.
- Use HTTPS — All API requests must use HTTPS. HTTP requests are rejected.
- Rotate secrets regularly — Regenerate your client secret periodically.
- Limit scopes — Only request the permissions you need.
- Monitor usage — Check the API usage logs in the Admin panel for unusual activity.
Troubleshooting Authentication
| Error | Cause | Solution |
|---|
401 Unauthorized | Token is missing, expired, or invalid | Obtain a new token or refresh the existing one |
403 Forbidden | Token is valid but lacks required scope | Add the needed scope to your API client |
invalid_client | Incorrect client_id or client_secret | Verify your credentials in Admin > API Keys |
invalid_grant | Authorization code expired or already used | Restart the authorization flow |
Next Steps
