Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Autenticação, Chaves de API e Organização

Aula 3 de 22 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Autenticação, Chaves de API e Organização
  2. Criar a Sua Conta e Obter uma Chave
  3. Que Tipo de Chave Escolher
  4. Organizações e Projetos
  5. Nunca Exponha as Suas Chaves
  6. Verificar a Sua Configuração
  7. Pontos-chave

Autenticação, Chaves de API e Organização

Antes de escrever uma única linha de código, tem de configurar o seu acesso à API. Esta lição abrange a criação de chaves, a estruturação do acesso através de organizações e projetos, e as precauções de segurança que previnem o pesadelo clássico: enviar acidentalmente uma chave para um repositório público, onde um estranho a consome durante a noite.

Criar a Sua Conta e Obter uma Chave

O processo consiste em três passos. Primeiro, aceda a platform.openai.com e crie uma conta; receberá automaticamente créditos gratuitos para começar a experimentar. De seguida, navegue até à secção API Keys do painel de controlo e gere uma nova chave. Só verá esta chave uma vez: copie-a imediatamente, mas não a cole no seu código.

# A sua chave de API tem este aspeto (nunca a partilhe!)
# sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Melhor prática: usar uma variável de ambiente
import os
api_key = os.environ.get("OPENAI_API_KEY")

O terceiro passo é declarar a variável de ambiente, o que depende da sua plataforma. Num computador de desenvolvimento, um ficheiro .env carregado pelo python-dotenv é frequentemente a opção mais conveniente. Num servidor, prefira uma variável de ambiente definida pelo seu orquestrador ou serviço de segredos.

# Linux / macOS — adicionar a ~/.bashrc ou ~/.zshrc
export OPENAI_API_KEY="sk-proj-your-key-here"

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-proj-your-key-here"

# Ficheiro .env (com python-dotenv)
# .env
OPENAI_API_KEY=sk-proj-your-key-here

Que Tipo de Chave Escolher

As chaves de projeto, identificáveis pelo prefixo sk-proj-, estão vinculadas a um projeto específico e oferecem o melhor controlo. Utilizá-las-á em quase todos os casos. O SDK deteta-as automaticamente assim que a variável de ambiente está definida, razão pela qual OpenAI() é instanciado sem argumentos em todos os exemplos deste curso.

from openai import OpenAI

# O SDK deteta automaticamente a OPENAI_API_KEY
client = OpenAI()

# Ou especificar explicitamente (não recomendado para produção)
client = OpenAI(api_key="sk-proj-...")

As chaves de serviço são o segundo tipo. Concebidas para aplicações de servidor que requerem acesso elevado, concedem permissões adicionais e, por conseguinte, exigem cuidado extra: guarde-as num cofre de segredos e nunca distribua o seu valor para uma estação de trabalho de desenvolvimento.

Organizações e Projetos

O acesso está estruturado em três níveis aninhados:

  1. Organization: A sua empresa ou equipa
  2. Project: Um agrupamento lógico (ex.: “Chatbot de Produção”, “Análise de Dados”)
  3. API Key: Vinculada a um projeto específico

Se pertencer a várias organizações, especifique aquela que pretende utilizar ao instanciar o cliente:

from openai import OpenAI

# Especificar a organização (útil se pertencer a várias)
client = OpenAI(
    organization="org-xxxxxxxxxxxx",
    project="proj-xxxxxxxxxxxx"
)

Dedique algum tempo a dividir a sua utilização em projetos, em vez de encaminhar tudo através de uma única chave. Verá o benefício ao primeiro sinal de problemas. Cada projeto tem o seu próprio rastreio de utilização, permitindo-lhe atribuir custos a uma funcionalidade específica em vez de um total mensal opaco. Os limites de taxa também são separados: um trabalho em lote noturno que sature a sua quota não impedirá o seu chatbot de responder aos clientes. Pode então atribuir diferentes membros a cada projeto e, crucialmente, revogar uma chave comprometida sem interromper outras aplicações.

Nunca Exponha as Suas Chaves

A regra é simples e absoluta: uma chave nunca aparece no código fonte. O contraste entre os dois excertos abaixo fala mais alto do que uma longa palestra.

# MAU — chave codificada no código
client = OpenAI(api_key="sk-proj-abc123")  # PERIGO!

# BOM — variável de ambiente
client = OpenAI()  # Lê automaticamente a OPENAI_API_KEY

# BOM — ficheiro .env com python-dotenv
from dotenv import load_dotenv
load_dotenv()
client = OpenAI()

O corolário diz respeito ao seu .gitignore, que deve excluir ficheiros de configuração locais antes do seu primeiro commit, e não depois. Uma chave que seja publicada e depois apagada permanece presente no histórico do repositório.

# ADICIONE SEMPRE estas linhas ao seu .gitignore
.env
.env.local
.env.production
*.key

Por fim, planeie uma rotação regular, a cada 90 dias. Pode fazê-lo sem tempo de inatividade: crie uma nova chave, atualize as suas implementações e, só depois, apague a antiga quando nada mais a estiver a utilizar.

Verificar a Sua Configuração

Antes de avançar, execute este script. Ele verifica a presença da chave, exibe uma versão truncada para confirmar que é a correta e, em seguida, faz uma chamada real. Volte a executar este teste sempre que um ambiente se comportar de forma estranha.

from openai import OpenAI
import os

def verify_configuration():
    """Verificar se a configuração da API está correta."""
    
    # Verificar a chave
    api_key = os.environ.get("OPENAI_API_KEY")
    if not api_key:
        print("ERRO: OPENAI_API_KEY não definida")
        return False
    
    print(f"Chave detetada: {api_key[:8]}...{api_key[-4:]}")
    
    # Testar a ligação
    try:
        client = OpenAI()
        response = client.responses.create(
            model="gpt-5.6-terra",
            input="Reply only: OK"
        )
        print(f"Ligação bem-sucedida: {response.output_text}")
        return True
    except Exception as e:
        print(f"ERRO de ligação: {e}")
        return False

verify_configuration()
# Resultado esperado:
# Chave detetada: sk-proj-...xxxx
# Ligação bem-sucedida: OK

Pontos-chave

  • Utilize chaves de projeto (sk-proj-...) para cada aplicação
  • Guarde as suas chaves em variáveis de ambiente, nunca no código
  • Organize o seu acesso com a hierarquia Organização → Projeto → Chave
  • Efetue a rotação regular das suas chaves (a cada 90 dias)
  • Adicione sempre .env ao seu .gitignore