Como funciona o token de acesso de longa duração do Facebook e os 60 dias dele

O que é um token de acesso de longa duração do Facebook?

A Meta emite um token de acesso de longa duração do Facebook em troca de um de curta duração, e a documentação dela coloca a vida desse token em cerca de 60 dias. A troca é uma única chamada no servidor. A razão de ela existir está na primeira linha do guia da Meta: "Default User and Page access tokens are short-lived, expiring in hours, however, you can exchange a short-lived token for a long-lived token."

A Meta traça a distinção em uma frase na visão geral de tokens de acesso: "Access tokens come in two forms: short-lived and long-lived. Short-lived tokens typically last about one to two hours, while long-lived tokens last about 60 days."

A frase que vem depois dessa é a que a maioria das integrações ignora. A Meta escreve que você não deve depender de esses tempos de vida permanecerem os mesmos, porque "they may change without warning or expire early."

Como trocar um token de curta duração por um de longa duração?

Você consulta o endpoint GET oauth/access_token com grant_type=fb_exchange_token. O exemplo em curl da própria Meta:

curl -i -X GET "https://graph.facebook.com/{graph-api-version}/oauth/access_token?
    grant_type=fb_exchange_token&
    client_id={app-id}&
    client_secret={app-secret}&
    fb_exchange_token={your-access-token}"

Quatro entradas, três delas suas. client_id é o App ID, client_secret é o App Secret, e fb_exchange_token é o token de acesso de Usuário de curta duração que você já tem. A resposta:

{
  "access_token": "{long-lived-user-access-token}",
  "token_type": "bearer",
  "expires_in": 5183944
}

A Meta anota o expires_in no próprio exemplo como "The number of seconds until the token expires." Vale fazer a conta desse número. Sessenta dias são 5.184.000 segundos. O valor documentado pela Meta é 5.183.944, que cai 56 segundos abaixo de 60 dias redondos. A diferença é irrelevante na prática e instrutiva em princípio: o número documentado não é uma promessa de exatamente 60 dias, é um valor de exemplo, e a Meta diz que o tempo de vida por trás dele pode mudar.

Três ressalvas vêm coladas na troca, nas palavras da Meta:

• "You can not use an expired token to request a long-lived token." Depois que o token de curta duração morre, o usuário precisa fazer login de novo.
• "Make this call from your server, not a client. Your app secret is included in this API call, so you should never make the request client-side."
• "Do not use the same long-lived tokens on more than one web client."

A segunda ressalva também carrega uma instrução de armazenamento que costuma ser pulada: o token de longa duração "will be a different string than the original token, so if you're storing these tokens, replace the old one."

Curta duração contra longa duração, em uma tabela

O mobile é a exceção que confunde quem lê sobre integrações web. A Meta escreve que "Native mobile apps using Facebook's SDKs get long-lived User access tokens, good for about 60 days. These tokens are refreshed once per day, when the person using your app makes a request to Facebook's servers." A renovação diária só acontece se a pessoa continuar usando o app, já que "If no requests are made, the token will expire after about 60 days."

Por que um token de acesso de Página se comporta diferente?

Um token de acesso de Página derivado de um token de acesso de Usuário de longa duração não expira. A Meta afirma isso claramente: "Long-lived Page access token do not have an expiration date and only expire or are invalidated under certain conditions."

Você obtém um chamando a edge accounts com o token de Usuário de longa duração:

curl -i -X GET "https://graph.facebook.com/{graph-api-version}/{app-scoped-user-id}/accounts?
  access_token={long-lived-user-access-token}"

A resposta devolve um objeto por Página, cada um carregando o próprio access_token, mais category, name, id e um array tasks com valores como ANALYZE, ADVERTISE, MODERATE, CREATE_CONTENT e MANAGE. Não existe expires_in nessa carga, que é a versão em formato de resposta da mesma afirmação.

Duas condições limitam isso. A Meta exige que "The person requesting the token must have a role on the Page", e observa em outro ponto que "Page access tokens are unique to each Page, admin, and app combination." Mude qualquer um desses três e você tem outro token, então um token de Página não sobrevive ao admin que o criou perder o papel dele.

Essa é a maior razão estrutural para integrações de publicação serem construídas sobre tokens de Página em vez de tokens de Usuário. Uma fila que precisa sobreviver a um relógio de 60 dias precisa de estratégia de renovação; uma fila sobre um token de Página não tem relógio a sobreviver. É também por isso que conectar uma conta do Instagram a uma Página comercial do Facebook importa para trabalho de API e não só para publicação cruzada, já que a Instagram API com Facebook Login autentica com um token de acesso de Página do Facebook.

O que invalida um token antes dos 60 dias?

A Meta nunca publica uma lista completa. A página do token de longa duração diz que tokens de Página "only expire or are invalidated under certain conditions" e aponta para a página de depuração para essas condições. Essa página nomeia uma causa geral e mostra três respostas de erro específicas, e nunca enumera as condições como lista.

A causa geral, citada: "Due to security related events, access tokens may be invalidated before the expected expiration time."

As três falhas documentadas, cada uma devolvendo o código 190:

Uma troca de senha é a que pega os times desprevenidos, porque invalida tokens sem culpa nenhuma da integração e não gera sinal algum. A Meta é explícita sobre a ausência desse sinal: "Facebook will not notify you that an access token has become invalid. Unless you have sent the expiry time to your app along with the access token, your app may only learn that a given token has become invalid when you attempt to make a request to the API."

Essa frase é o coração operacional do assunto inteiro. Não existe webhook para um token morto. Um post agendado é onde a maioria dos times descobre o problema, e é por isso que um token morto fica no topo da lista de razões para posts agendados do Facebook pararem de funcionar sem nenhuma mudança óbvia do lado da publicação.

Como conferir o que um token ainda tem de vida?

Consulte o debug_token em vez de confiar no número de 60 dias:

curl -i -X GET "https://graph.facebook.com/debug_token?
  input_token={input-token}&
  access_token={valid-access-token}"

A Meta acrescenta uma restrição: "The tokens must be from the same app." A resposta devolve app_id, type, application, expires_at, data_access_expires_at, is_valid, scopes, granular_scopes e user_id, e a Meta observa que "For long-lived access tokens the issued_at field is also returned."

Dois desses campos são relógios separados e vivem sendo confundidos. expires_at é quando o token para de funcionar. data_access_expires_at é um prazo diferente que rege o acesso continuado aos dados do usuário. Um token pode ser válido contra o primeiro e restrito pelo segundo.

Construa a checagem no pipeline, não em um manual. Ler expires_at antes de uma publicação custa uma requisição e transforma uma falha silenciosa em uma reautorização agendada, do mesmo jeito que ler o content_publishing_limit do Instagram antes de publicar transforma um limite de taxa em uma decisão de fila. As duas são leituras baratas que trocam um erro imprevisível por um número que você consegue prever.

Uma classe de app escapa do relógio por completo. A Meta escreve que "Apps with Standard access to the Marketing API receive long-lived tokens that do not expire based on time, though they are still subject to invalidation for other reasons", e estende isso a tokens de Usuário de Sistema no Business Manager. O tempo deixa de ser o modo de falha; as invalidações por evento de segurança não deixam.

Perguntas frequentes

Quanto tempo dura um token de acesso de longa duração do Facebook?

Cerca de 60 dias. A resposta de exemplo da Meta devolve expires_in: 5183944 segundos, que são 56 segundos abaixo de 60 dias, e a Meta avisa que o tempo de vida "may change without warning."

Qual é o endpoint exato da troca?

GET https://graph.facebook.com/{graph-api-version}/oauth/access_token com grant_type=fb_exchange_token, client_id, client_secret e fb_exchange_token. Ele precisa rodar no servidor porque carrega o app secret.

Dá para renovar um token de longa duração antes de ele expirar?

A Meta documenta a troca apenas de curta duração para longa duração, e afirma que "You can not use an expired token to request a long-lived token." Ela não documenta uma renovação de um token de Usuário já de longa duração na web.

Tokens de acesso de Página chegam a expirar?

A Meta diz que tokens de Página gerados a partir de um token de acesso de Usuário de longa duração "do not have an expiration date and only expire or are invalidated under certain conditions", e nunca publica essas condições como lista completa.

O Facebook avisa quando um token morre?

Não. A documentação da Meta afirma diretamente que "Facebook will not notify you that an access token has become invalid", e que seu app pode só descobrir quando uma requisição falha.

Qual erro significa que o usuário trocou a senha?

Código 190, subcódigo 460, com a mensagem "Error validating access token: The session is invalid because the user logged out." A Meta atribui essa resposta a uma pessoa que "logged out of your app or changed their password."

O que acontece se seu token de curta duração já expirou antes da troca?

O Meta bloqueia a troca de vez: "You can not use an expired token to request a long-lived token." O token de curta duração precisa estar vivo no momento da chamada a oauth/access_token, então esperar demais depois do login deixa só uma saída, passar de novo pelo fluxo de login.

Um mesmo token de longa duração pode atender dois clientes web diferentes?

O aviso do Meta é direto: "Do not use the same long-lived tokens on more than one web client." Cada cliente web deve fazer sua própria troca e guardar seu próprio token em vez de compartilhar um entre várias propriedades.

O que acontece com a string do token de curta duração depois da troca?

O token de longa duração que o Meta devolve "will be a different string than the original token", então qualquer armazenamento feito para o token curto precisa ser atualizado. A instrução do Meta é direta: quem guarda esses tokens deve substituir o antigo em vez de manter os dois.

Os tokens da Marketing API seguem o mesmo relógio de 60 dias?

Apps com acesso Standard à Marketing API recebem, segundo o Meta, tokens de longa duração que não expiram por tempo, embora continuem sujeitos a invalidação por outros motivos. O Meta estende a mesma exceção aos tokens de System User no Business Manager. O relógio de 60 dias simplesmente não vale ali, mas invalidações por eventos de segurança continuam valendo.