API Key Management API keys allow your integrations to authenticate with SalesOS. You can create and manage keys in two ways:
Via Dashboard Point-and-click — best for most users
Via API Programmatic — for automation and CI/CD
API key management requires the admin.integrations capability. Tenant owners and admins have this by default.
Via Dashboard The simplest way to create an API key is through the SalesOS Dashboard.
Navigate to API Keys
Go to Integrations > API Keys in the sidebar menu.
Create a new key
Click Create API Key and fill in:
Name — A descriptive name (e.g., “CRM Nightly Sync”, “Website Forms”)Scope — Select default:sync for standard integrationsRate limit — Requests per hour (default: 1,000)Expiration — Optional expiry date
Copy your key
Your API key will be displayed once : sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Copy it immediately and store it in a secure location (e.g., environment variable, secrets manager).The key is shown only once after creation. If you lose it, you’ll need to create a new one and revoke the old one.
Managing keys in the Dashboard From the same Integrations > API Keys page you can:
View all active, revoked, and expired keysRevoke a key — immediately stops it from workingDelete a key — permanently removes it (prefer revoking to keep audit history)Monitor usage — see request count and last used date
Via API For automation, CI/CD pipelines, or custom admin panels, you can manage keys programmatically.
Authentication Method Who How JWT (Bearer token) Tenant admins Token from Dashboard session. Keys are scoped to your tenant automatically. service_role Platform admins Internal service key. Must provide X-Tenant-Id header or tenant_id in body.
BOLA Prevention : When using JWT auth, the tenant_id field in request bodies is ignored . The API always uses the tenant from your session — you cannot create or manage keys for other tenants.
Create a Key cURL (JWT)
cURL (service_role)
JavaScript
# Get your JWT from the Dashboard session curl -X POST https://api-staging.play2sell.com/functions/v1/api-key-admin \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "key_name": "CRM Nightly Sync", "scopes": ["default:sync"], "rate_limit_per_hour": 5000, "expires_in_days": 90, "environment": "live" }'
curl -X POST https://api-staging.play2sell.com/functions/v1/api-key-admin \ -H "Authorization: Bearer SUPABASE_SERVICE_ROLE_KEY" \ -H "X-Tenant-Id: YOUR_TENANT_UUID" \ -H "Content-Type: application/json" \ -d '{ "tenant_id": "YOUR_TENANT_UUID", "key_name": "CRM Nightly Sync", "scopes": ["default:sync"], "rate_limit_per_hour": 5000 }'
const response = await fetch ( 'https://api-staging.play2sell.com/functions/v1/api-key-admin' , { method: 'POST' , headers: { 'Authorization' : `Bearer ${ jwtToken } ` , 'Content-Type' : 'application/json' , }, body: JSON . stringify ({ key_name: 'CRM Nightly Sync' , scopes: [ 'default:sync' ], rate_limit_per_hour: 5000 , expires_in_days: 90 , }), } ); const { api_key , warning } = await response . json (); console . log ( 'Save this key:' , api_key ); // => sk_live_a1b2c3d4e5f6...
Response (201): { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "key_prefix" : "sk_live_" , "key_last_4" : "f6g7" , "scopes" : [ "default:sync" ], "rate_limit_per_hour" : 5000 , "expires_at" : "2026-06-17T00:00:00.000Z" , "created_at" : "2026-03-17T14:30:00.000Z" , "tenant_id" : "b2c3d4e5-f6g7-8901-abcd-ef2345678901" , "tenant_name" : "Acme Corp" , "api_key" : "sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0" , "warning" : "Save this API key now. It cannot be retrieved again." }
The api_key field is shown only once . If you lose it, you must create a new key.
List Keys curl https://api-staging.play2sell.com/functions/v1/api-key-admin \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response (200): { "keys" : [ { "id" : "a1b2c3d4-..." , "key_name" : "CRM Nightly Sync" , "key_prefix" : "sk_live_" , "key_last_4" : "f6g7" , "scopes" : [ "default:sync" ], "status" : "active" , "rate_limit_per_hour" : 5000 , "usage_count" : 1247 , "last_used_at" : "2026-03-17T10:00:00.000Z" , "expires_at" : "2026-06-17T00:00:00.000Z" , "created_at" : "2026-03-01T09:00:00.000Z" , "revoked_at" : null , "revoked_reason" : null } ], "total" : 1 }
The full API key and key hash are never returned in list responses.
Revoke a Key curl -X PUT https://api-staging.play2sell.com/functions/v1/api-key-admin/KEY_UUID/revoke \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{"reason": "Rotating credentials"}'
Response (200): { "id" : "a1b2c3d4-..." , "key_name" : "CRM Nightly Sync" , "key_prefix" : "sk_live_" , "key_last_4" : "f6g7" , "status" : "revoked" , "revoked_at" : "2026-03-17T15:00:00.000Z" , "revoked_reason" : "Rotating credentials" }
Delete a Key curl -X DELETE https://api-staging.play2sell.com/functions/v1/api-key-admin/KEY_UUID \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Prefer revoking over deleting. Revoked keys preserve audit history (who created it, when it was used, why it was revoked).
Available Scopes Scope Grants access to default:syncsync_collaborators and sync_activities endpointsleads:readRead lead data leads:writeCreate and update leads
An empty scopes array means the key has no scope restriction — it can access any endpoint that accepts API key auth.
Best Practices
Use multiple keys for different integrations
Create separate keys for each integration (CRM sync, website forms, partner API). This way, if one key is compromised, you only need to rotate that one.
Keys without expiration live forever. Set expires_in_days to enforce regular rotation — 90 days is a good default.
If a key only needs to sync activities, give it default:sync only. Don’t leave scopes empty unless the key truly needs full access.
Check usage_count and last_used_at in the list response. Keys that haven’t been used in months may be candidates for revocation.
Rotate keys without downtime
Create a new key
Update your integration to use the new key
Verify the new key works
Revoke the old key
Next Steps
Authentication Learn about API key formats and security
Default Integration Start sending activities with your new key
