Gerenciamento de API Keys API keys permitem que suas integracoes se autentiquem com o SalesOS. Voce pode criar e gerenciar chaves de duas formas:
Pelo Dashboard Interface visual — ideal para a maioria dos usuarios
Via API Programatico — para automacao e CI/CD
O gerenciamento de API keys requer a capability admin.integrations . Owners e admins do tenant possuem isso por padrao.
Pelo Dashboard A forma mais simples de criar uma API key e pelo Dashboard do SalesOS.
Navegue ate API Keys
Va em Integracoes > API Keys no menu lateral.
Crie uma nova chave
Clique em Criar API Key e preencha:
Nome — Um nome descritivo (ex.: “Sincronizacao CRM Noturna”, “Formularios do Site”)Escopo — Selecione default:sync para integracoes padraoRate limit — Requisicoes por hora (padrao: 1.000)Expiracao — Data de expiracao opcional
Copie sua chave
Sua API key sera exibida uma unica vez : sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Copie imediatamente e armazene em local seguro (ex.: variavel de ambiente, gerenciador de segredos).A chave e exibida apenas uma vez apos a criacao. Se voce perder, precisara criar uma nova e revogar a antiga.
Gerenciando chaves no Dashboard Na mesma pagina Integracoes > API Keys voce pode:
Visualizar todas as chaves ativas, revogadas e expiradasRevogar uma chave — para de funcionar imediatamenteExcluir uma chave — remove permanentemente (prefira revogar para manter historico de auditoria)Monitorar uso — veja contagem de requisicoes e data do ultimo uso
Via API Para automacao, pipelines CI/CD ou paineis admin customizados, voce pode gerenciar chaves programaticamente.
Autenticacao Metodo Quem Como JWT (Bearer token) Admins do tenant Token da sessao do Dashboard. As chaves sao associadas ao seu tenant automaticamente. service_role Admins da plataforma Chave interna de servico. Deve fornecer header X-Tenant-Id ou tenant_id no body.
Prevencao BOLA : Ao usar autenticacao JWT, o campo tenant_id no body da requisicao e ignorado . A API sempre usa o tenant da sua sessao — voce nao pode criar ou gerenciar chaves de outros tenants.
Criar uma Chave cURL (JWT)
cURL (service_role)
JavaScript
# Obtenha seu JWT da sessao do Dashboard curl -X POST https://api-staging.play2sell.com/functions/v1/api-key-admin \ -H "Authorization: Bearer SEU_TOKEN_JWT" \ -H "Content-Type: application/json" \ -d '{ "key_name": "Sincronizacao CRM Noturna", "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: UUID_DO_TENANT" \ -H "Content-Type: application/json" \ -d '{ "tenant_id": "UUID_DO_TENANT", "key_name": "Sincronizacao CRM Noturna", "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: 'Sincronizacao CRM Noturna' , scopes: [ 'default:sync' ], rate_limit_per_hour: 5000 , expires_in_days: 90 , }), } ); const { api_key , warning } = await response . json (); console . log ( 'Salve esta chave:' , api_key ); // => sk_live_a1b2c3d4e5f6...
Resposta (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." }
O campo api_key e exibido apenas uma vez . Se voce perder, precisara criar uma nova chave.
Listar Chaves curl https://api-staging.play2sell.com/functions/v1/api-key-admin \ -H "Authorization: Bearer SEU_TOKEN_JWT"
Resposta (200): { "keys" : [ { "id" : "a1b2c3d4-..." , "key_name" : "Sincronizacao CRM Noturna" , "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 }
A chave completa e o hash nunca sao retornados nas respostas de listagem.
Revogar uma Chave curl -X PUT https://api-staging.play2sell.com/functions/v1/api-key-admin/KEY_UUID/revoke \ -H "Authorization: Bearer SEU_TOKEN_JWT" \ -H "Content-Type: application/json" \ -d '{"reason": "Rotacao de credenciais"}'
Resposta (200): { "id" : "a1b2c3d4-..." , "key_name" : "Sincronizacao CRM Noturna" , "key_prefix" : "sk_live_" , "key_last_4" : "f6g7" , "status" : "revoked" , "revoked_at" : "2026-03-17T15:00:00.000Z" , "revoked_reason" : "Rotacao de credenciais" }
Excluir uma Chave curl -X DELETE https://api-staging.play2sell.com/functions/v1/api-key-admin/KEY_UUID \ -H "Authorization: Bearer SEU_TOKEN_JWT"
Prefira revogar em vez de excluir. Chaves revogadas preservam o historico de auditoria (quem criou, quando foi usada, por que foi revogada).
Escopos Disponiveis Escopo Concede acesso a default:syncEndpoints sync_collaborators e sync_activities leads:readLeitura de dados de leads leads:writeCriacao e atualizacao de leads
Um array scopes vazio significa que a chave nao tem restricao de escopo — pode acessar qualquer endpoint que aceite autenticacao por API key.
Boas Praticas
Use chaves diferentes para cada integracao
Crie chaves separadas para cada integracao (sincronizacao CRM, formularios do site, API de parceiros). Assim, se uma chave for comprometida, voce so precisa rotacionar aquela.
Defina datas de expiracao
Chaves sem expiracao vivem para sempre. Defina expires_in_days para forcar rotacao regular — 90 dias e um bom padrao.
Se uma chave so precisa sincronizar atividades, de apenas default:sync. Nao deixe escopos vazios a menos que a chave realmente precise de acesso total.
Verifique usage_count e last_used_at na resposta de listagem. Chaves nao usadas ha meses podem ser candidatas a revogacao.
Rotacione chaves sem downtime
Crie uma nova chave
Atualize sua integracao para usar a nova chave
Verifique que a nova chave funciona
Revogue a chave antiga
Proximos Passos
Autenticacao Saiba mais sobre formatos de API key e seguranca
Integracao Padrao Comece a enviar atividades com sua nova chave
