BR
Guia de access tokens

Token de acesso da API do Facebook: tokens de usuário, Página, app e usuário do sistema

Como obter cada token, estendê-lo para cerca de 60 dias, verificá-lo com debug_token e tratar o erro 190, e como um SaaS pode dispensar todo o fluxo de tokens.

Verificação do token 200 OK
GETgraph.facebook.com/debug_token?input_token={USER_ACCESS_TOKEN}
applicationSeu app
is_validtrue
expires_atem 60 diastoken de usuário de longa duração
data_access_expires_atem 90 diasrenovado quando o usuário está ativo
scopespublic_profilepages_show_list
TOKEN Sem refresh token: verifique, depois peça novo login
Resposta curta

Um token de acesso da API do Facebook é a string que toda chamada à Graph API exige. Você obtém um token de usuário pelo Facebook Login (ou pelo Graph API Explorer, para testes), troca-o no seu servidor por um token de longa duração de cerca de 60 dias e depois chama /me/accounts para obter os tokens de Página. Não existe chave de API nem refresh token: monitore os tokens com debug_token e trate o erro 190.

Para um SaaS que atende muitos clientes, existe um segundo modelo: os usuários conectam as próprias contas do Facebook pela Unipile, e o seu app nunca guarda um token da Meta.

Com a Unipile

Nenhum token da Meta para obter, estender ou depurar

  1. 1

    Conecte a conta

    O seu usuário conecta a conta do Facebook ou a Página uma única vez pelo Hosted Auth. Sem app da Meta, sem App Review.

  2. 2

    Chame com a sua chave de API

    Envie X-API-KEY com o account_id do usuário: GET /v2/{ACCOUNT_ID}/chats.

  3. 3

    Acompanhe um único status

    Verifique products_connection_status; se necessário, o usuário se reconecta pelo Hosted Auth.

Definição

O que é um token de acesso da API do Facebook?

A Meta define um access token como "uma string opaca que identifica um usuário, um app ou uma Página do Facebook". Toda requisição à Graph API leva um, e o tipo dele determina em nome de quem você age.

TokenAge em nome deComo obterDuração e uso
UsuárioUma pessoa logadaFacebook Login ou Graph API Explorer1 a 2 horas, ou cerca de 60 dias
PáginaUma Página do Facebook/me/accounts com o token de usuário de um adminSegue o token de usuário
AppO seu app da MetaChamada client_credentials, ou {APP_ID}|{APP_SECRET}Só chamadas servidor a servidor
Usuário do sistemaA sua empresaBusiness SettingsSem expiração, ou 60 dias
ClienteO seu app, no código clienteApp DashboardNão é um segredo
Token de usuário
Age em nome deUma pessoa logada
Como obterFacebook Login ou Graph API Explorer
Duração e uso1 a 2 horas, ou cerca de 60 dias
Token de Página
Age em nome deUma Página do Facebook
Como obter/me/accounts com o token de usuário de um admin
Duração e usoSegue o token de usuário
Token de app
Age em nome deO seu app da Meta
Como obterChamada client_credentials, ou {APP_ID}|{APP_SECRET}
Duração e usoSó chamadas servidor a servidor
Token de usuário do sistema
Age em nome deA sua empresa
Como obterBusiness Settings
Duração e usoSem expiração, ou 60 dias
Token de cliente
Age em nome deO seu app, no código cliente
Como obterApp Dashboard
Duração e usoNão é um segredo

O Instagram tem o próprio fluxo: veja o nosso guia do token da API do Instagram.

Fonte: guia Access Tokens da Meta. Última verificação: 17 de novembro de 2026.

Obter um token

Como obter um token de acesso da API do Facebook

Não existe chave de API do Facebook: toda chamada usa um access token. Para testes, gere um para a sua própria conta no Graph API Explorer. Em produção, os usuários entram no seu app da Meta com o Facebook Login (for Business, quando você precisa das Páginas deles), e o seu servidor troca o code retornado por um user access token.

Teste, em 4 etapas

Graph API Explorer

  1. Abra developers.facebook.com/tools/explorer
  2. Escolha o seu app da Meta e "User Token"
  3. Adicione as permissões necessárias
  4. Clique em Generate Access Token e aprove
Produção, em 4 etapas

Facebook Login no seu app da Meta

  1. Crie um app da Meta (App ID, App Secret)
  2. Envie os usuários para /dialog/oauth com client_id, redirect_uri, state
  3. Eles concedem as permissões; você recebe um code
  4. O seu servidor chama /oauth/access_token com o code e o App Secret

A resposta traz access_token, token_type e expires_in. Outras pessoas só podem conceder permissões depois que o App Review dá Advanced Access ao seu app. O caminho de acesso completo está no nossa visão geral da API do Facebook, e o lado das Páginas no nosso guia da API de Páginas do Facebook.

Fonte: guia Manually Build a Login Flow da Meta (Graph API v27.0). Última verificação: 17 de novembro de 2026.

Token de longa duração

Como obter um access token de longa duração

Envie o token de usuário de curta duração para GET /oauth/access_token com grant_type=fb_exchange_token, o seu App ID e o seu App Secret. A resposta traz um token de longa duração e o seu expires_in, cerca de 60 dias. A Meta é explícita: "faça essa chamada a partir do seu servidor, não de um cliente".

  • Troque antes da expiração. "Não é possível usar um token expirado para solicitar um token de longa duração": depois que o token curto expira, o usuário precisa fazer login de novo.
  • Armazene a expiração como uma data ao lado do token.
  • Só para testes? O Access Token Debugger tem um botão Extend Access Token que faz o mesmo para um token seu.

O ciclo de vida do token em código

As abas 1 a 3 usam a Graph API da Meta; a aba 4 é a Unipile, sem token da Meta.

# Server side only: this call carries your App Secret
curl -G "https://graph.facebook.com/oauth/access_token" \
  -d "grant_type=fb_exchange_token" \
  -d "client_id={APP_ID}" \
  -d "client_secret={APP_SECRET}" \
  -d "fb_exchange_token={USER_ACCESS_TOKEN}"

# Response (abridged)
{ "access_token": "{LONG_LIVED_USER_TOKEN}", "expires_in": 5183944 }
# App access token, for server-to-server calls such as debug_token
curl -G "https://graph.facebook.com/oauth/access_token" \
  -d "client_id={APP_ID}" \
  -d "client_secret={APP_SECRET}" \
  -d "grant_type=client_credentials"

# Or pass it directly, without the call
access_token={APP_ID}|{APP_SECRET}
# Check any token with your app token
curl -G "https://graph.facebook.com/debug_token" \
  -d "input_token={LONG_LIVED_USER_TOKEN}" \
  -d "access_token={APP_ID}|{APP_SECRET}"

# Response (abridged)
{ "data": {
    "app_id": "{APP_ID}",
    "is_valid": true,
    "expires_at": 1800057600,
    "data_access_expires_at": 1802649600,
    "scopes": ["public_profile", "pages_show_list"]
} }
# No Meta token: your API key and the user's account_id
curl --request GET \
  --url "https://api.unipile.com/v2/{ACCOUNT_ID}/inboxes" \
  --header "X-API-KEY: {API_KEY}"

# List the chats of the connected account
curl --request GET \
  --url "https://api.unipile.com/v2/{ACCOUNT_ID}/chats" \
  --header "X-API-KEY: {API_KEY}"
200 OK · token de usuário de longa duração, cerca de 60 dias
200 OK · nunca no código cliente nem nos binários do app
200 OK · is_valid, expires_at, data_access_expires_at
200 OK · um account_id, nenhum token para trocar

Requisições extraídas dos guias Long-Lived Access Tokens e Access Tokens da Meta. Unipile: documentação de Páginas do Facebook.

Tokens de Página, em resumo

Com o token de usuário de longa duração de um admin da Página, GET /me/accounts retorna cada Página com o próprio token, que "não tem data de expiração e só expira ou é invalidado em certas condições". Detalhes no nosso guia da API de Páginas do Facebook; para publicar com ele, veja como publicar em uma Página com o token dela.

Duração

Quanto tempo dura um access token do Facebook?

Segundo a Meta, um token de usuário de curta duração dura de uma a duas horas e um de longa duração cerca de 60 dias. Os tokens de Página obtidos a partir de um token de longa duração e alguns tokens de usuário do sistema não têm data de expiração. À parte disso, o seu acesso aos dados de um usuário termina após 90 dias de inatividade.

Facebook Duração dos tokens, segundo a Meta
Token de usuário de curta duração1 a 2 horas
Token de usuário de longa duraçãoCerca de 60 dias
Token de Página, a partir de um token de usuário de longa duraçãoSem data de expiração
Token de usuário do sistemaNunca, ou 60 dias
Acesso aos dados do usuário90 dias após a última atividade
Expiração do token não é expiração do acesso aos dados

A Meta afirma que "o período de expiração do acesso aos dados é de 90 dias, com base na última vez em que o usuário esteve ativo". O usuário continua logado, mas o seu app não consegue ler os dados dele até que ele autorize o app de novo.

Nenhum token é permanente: um token que "nunca expira" ainda deixa de funcionar quando o usuário remove o seu app, muda a senha ou perde a função. A Meta avisa: "não conte com que essas durações permaneçam as mesmas".

Fontes: Access Tokens, Long-Lived Access Tokens, Authorization vs. data access e tokens de usuário do sistema da Meta. Última verificação: 17 de novembro de 2026.

Usuário do sistema

Tokens de acesso de usuário do sistema para processos servidor a servidor

Um token de acesso de usuário do sistema pertence a um usuário do sistema do seu Business Manager, não a uma pessoa. Segundo a Meta, ele permite que "o seu app execute ações programáticas e automatizadas em objetos de anúncio ou Páginas". Você o gera no Business Settings.

Opção 1

Nunca expira

Sem renovação, para os casos em que um vazamento do token é um risco aceitável.

Opção 2, recomendada

Expira em 60 dias

Defina set_token_expires_in_60_days=true e renove com fb_exchange_token antes do dia 60.

  • Só a mesma empresa. O usuário do sistema e o app pertencem ao mesmo Business Manager, e "se o usuário não tiver acesso, a requisição é rejeitada".
  • Acesso à Marketing API antes: acesso padrão ou superior.

Fontes: Install apps and generate tokens e Access Tokens da Meta. Última verificação: 17 de novembro de 2026.

Depuração

Como verificar um access token do Facebook com debug_token

Chame GET /debug_token?input_token={TOKEN} com um app access token (ou o token de usuário de um desenvolvedor do app). A resposta traz a validade, a expiração, a expiração do acesso aos dados e as permissões concedidas. Sem código, cole o token no Access Token Debugger (developers.facebook.com/tools/debug/accesstoken).

Facebook O que o debug_token retorna
is_validSe o token ainda funciona.
expires_atExpiração do token, em timestamp Unix; 0 significa sem data de expiração.
data_access_expires_atQuando o acesso aos dados termina, mesmo com um token válido.
scopesPermissões concedidas; granular_scopes acrescenta os IDs de destino.
app_id, user_idPara quem o token foi emitido.
profile_idO ID da Página, para um token de Página.

Para verificar se um access token do Facebook é válido em produção, execute a requisição da aba 3 do bloco de código acima no seu servidor, de forma agendada, e armazene as duas datas com cada token. Uma permissão ausente em scopes explica a maioria dos bugs do tipo "funciona para mim, falha para eles".

Fonte: referência do debug_token da Meta (Graph API v27.0). Última verificação: 17 de novembro de 2026.

Erros

Erros de access token do Facebook: o código 190 e seus subcódigos

O erro 190 significa que o access token do Facebook expirou ou é inválido. Ele chega como OAuthException, e o seu error_subcode indica o que pedir ao usuário. Tentar de novo com o mesmo token nunca resolve.

Facebook O que a Graph API retorna

{ "error": { "type": "OAuthException", "code": 190, "error_subcode": 460, "fbtrace_id": "EJplcsCHuLu" } }

190 Leia o error_subcode, guarde o fbtrace_id para o suporte da Meta
SubcódigoSignificadoO que fazer
458App não instaladoPeça um novo login ao usuário
459Usuário em checkpointO usuário entra no facebook.com
460Senha alteradaPeça um novo login ao usuário
463Token expiradoNovo login, depois nova troca
464Usuário não confirmadoO usuário entra no facebook.com
467Token inválidoReconecte o usuário
492Sem função adequada na PáginaNovo token de um admin atual
Subcódigo 458
SignificadoApp não instalado
O que fazerPeça um novo login ao usuário
Subcódigo 459
SignificadoUsuário em checkpoint
O que fazerO usuário entra no facebook.com
Subcódigo 460
SignificadoSenha alterada
O que fazerPeça um novo login ao usuário
Subcódigo 463
SignificadoToken expirado
O que fazerNovo login, depois nova troca
Subcódigo 464
SignificadoUsuário não confirmado
O que fazerO usuário entra no facebook.com
Subcódigo 467
SignificadoToken inválido
O que fazerReconecte o usuário
Subcódigo 492
SignificadoSem função adequada na Página
O que fazerNovo token de um admin atual

Em um SaaS com vários clientes, o 492 é o clássico: o admin que conectou uma Página sai da empresa. Os outros códigos estão na nossa tabela de erros da API do Facebook.

Fonte: guia de tratamento de erros da Graph API da Meta. Última verificação: 17 de novembro de 2026.

Segurança

Armazenar e proteger os access tokens do Facebook

Trate cada access token do Facebook como a senha da conta por trás dele: mantenha o App Secret e os tokens de app no seu servidor, criptografe os tokens de usuário e de Página em repouso, assine as chamadas do servidor com appsecret_proof e exclua os tokens assim que um cliente se desconectar.

  • Segredos só no servidor. A Meta: "nunca coloque app access tokens fixos no código cliente nem nos binários do app" e "use app access tokens apenas em chamadas servidor a servidor".
  • Os tokens de cliente são públicos. A Meta observa que eles "não são secretos", então nunca use um para autorizar algo sensível.
  • Assine as chamadas com appsecret_proof. A Meta o define como "um hash sha256 do seu access token, usando o app secret como chave"; ative Require App Secret no App Dashboard.
  • Criptografia em repouso, HTTPS em trânsito. Mantenha os tokens fora dos logs e das URLs.
  • Um registro por token. Armazene o usuário, a Página, o app e o expires_at.
  • Exclua ao desconectar. Apague o token quando um usuário sair.

Fontes: guias Access Tokens e Securing Requests da Meta. Última verificação: 17 de novembro de 2026.

Com a Unipile

Dispense a gestão de tokens: conecte as contas do Facebook dos seus usuários

Com a Unipile, cada usuário conecta a própria conta do Facebook uma única vez, pelo Hosted Auth. As Páginas que ele gerencia chegam no mesmo account_id, e você chama a API com a sua própria chave (X-API-KEY). Sem token da Meta, sem app da Meta e sem App Review do seu lado.

PerguntaAccess tokens da MetaConta conectada à Unipile
O que você armazenaUm token por usuário, mais um por Página, admin e appUm account_id por usuário e uma chave de API
O que você monitoraexpires_at e data_access_expires_at de cada tokenUm status por Página em metadata.products_connection_status
O que você renovaTroca por longa duração ou login antes do dia 60Nenhum token da Meta para trocar
No erro 190Analisar o subcódigo e pedir um novo login ao usuárioO usuário se reconecta pelo Hosted Auth, se necessário
O que você armazena
Tokens da MetaUm token por usuário, mais um por Página, admin e app
UnipileUm account_id por usuário e uma chave de API
O que você monitora
Tokens da Metaexpires_at e data_access_expires_at de cada token
UnipileUm status por Página em metadata.products_connection_status
O que você renova
Tokens da MetaTroca por longa duração ou login antes do dia 60
UnipileNenhum token da Meta para trocar
No erro 190
Tokens da MetaAnalisar o subcódigo e pedir um novo login ao usuário
UnipileO usuário se reconecta pelo Hosted Auth, se necessário

Uma conta conectada cobre mensagens, caixas de entrada de Páginas, posts, comentários e reações. Uma Página pode responder às suas conversas e publicar posts, mas não pode iniciar uma conversa. Veja a aba 4 acima e a nossa página da API do Facebook Messenger.

Conformidade

Cada usuário conecta a própria conta

A Unipile é uma empresa independente, não é um app oficial da Meta nem um Meta Partner. Ela age em nome de cada usuário autenticado, e cada usuário continua sujeito aos termos da Meta.

Desenvolva no Facebook sem um fluxo de tokens

Cada usuário vincula a própria conta do Facebook uma única vez; você usa uma só API para Facebook, LinkedIn, WhatsApp e e-mail. Teste grátis de 7 dias.

Comissão Europeia
Regulamentado pela UE Digital Markets Act (DMA)

Cada usuário conecta a própria conta, sem armazenamento de perfis. A Unipile não é Meta Partner. Saiba mais

Todos os endpoints da API do Facebook em um só lugar

Depois que a conta estiver conectada, veja todos os endpoints do Facebook disponíveis com a Unipile, ou leia o guia completo da API do Facebook para permissões, limites e erros.

FAQ sobre o token de acesso da API do Facebook

Respostas rápidas sobre duração, renovação, verificação de validade, armazenamento de tokens e o erro 190.

Não de verdade. Um token de usuário de longa duração dura cerca de 60 dias. Os tokens de Página obtidos a partir dele e alguns tokens de usuário do sistema não têm data de expiração, mas ainda deixam de funcionar quando o usuário remove o seu app, muda a senha ou perde a função. Preveja um fluxo de reconexão.

Não no sentido do OAuth: a Meta não documenta nenhum grant refresh_token para o Facebook Login. Você troca um token de curta duração ainda válido com fb_exchange_token; depois que um token expira, o usuário faz login de novo. Em apps móveis nativos, a Meta renova os tokens de longa duração uma vez por dia quando a pessoa usa o seu app.

Porque 60 dias é um teto, não uma promessa. Um token deixa de funcionar antes quando o usuário muda a senha, remove o seu app, cai em um checkpoint de segurança ou perde a função na Página, e a Meta avisa que as durações "podem mudar sem aviso ou expirar antes". Leia o error_subcode do erro 190 para saber em qual caso você está.

Chame GET /debug_token?input_token={TOKEN} com o seu app access token e leia is_valid, expires_at, data_access_expires_at e scopes. Para uma verificação pontual, cole o token no Access Token Debugger da Meta.

Sim, se você os tratar como senhas: criptografe-os em repouso, mantenha-os fora dos logs e do código cliente, e use o App Secret e os tokens de app apenas em chamadas servidor a servidor. Assine as chamadas do servidor com appsecret_proof.

O erro 190 com o subcódigo 492 indica uma sessão inválida: o usuário por trás de um Page access token não tem mais uma função adequada na Página. Obtenha um novo token de Página de um admin atual.

Não. A Unipile é uma empresa independente: não é Meta Partner, não é um app oficial da Meta e não é endossada, patrocinada nem aprovada pela Meta. Facebook é uma marca registrada da Meta Platforms, Inc.

Não. Você chama a Unipile com a sua chave de API e o account_id de cada usuário conectado. Os usuários vinculam a conta do Facebook e as Páginas que gerenciam pela autenticação hospedada da Unipile: sem app da Meta, App Secret nem App Review do seu lado.

Ela foi projetada em conformidade com o Digital Markets Act: cada usuário conecta a própria conta, e a Unipile age em nome dele sem armazenar perfis de usuários. Saiba mais na nossa página sobre o Digital Markets Act.

Sim. Cada conta conectada continua sujeita aos Termos de Serviço da Meta. Use a API para cenários legítimos, como atendimento ao cliente, CRM e conversas diretas; spam e automação não autorizada podem levar à restrição das contas.

Ainda tem dúvidas? Nossa equipe está aqui para ajudar.

Fale com um especialista