Por que um access token do LinkedIn expira depois de 60 dias

Quanto tempo dura um access token do LinkedIn?

Todo access token do LinkedIn emitido pelo fluxo de authorization code carrega o mesmo relógio, e o LinkedIn declara a cifra sem ressalva: "Currently, all access tokens are issued with a 60-day lifespan." Essa linha fica na tabela de campos de resposta do expires_in na página do OAuth de três pernas, que é o fluxo usado por qualquer integração de publicação.

A resposta de exemplo que o LinkedIn publica nessa página bate com a frase até o segundo:

{
  "access_token":"AQUvlL_DYEzvT2wz1QJiEPeLioeA",
  "expires_in":5184000,
  "scope":"r_basicprofile"
}

5.184.000 segundos são 60 dias exatos, sem nada raspado. Leia o campo em vez da frase, porém. A própria orientação do LinkedIn diz que "Access tokens stay valid until the number of seconds indicated in the expires_in field in the API response," e o expires_in é o único valor que reflete o que o seu token de fato recebeu.

Quais tokens do LinkedIn têm qual tempo de vida?

São três, e não se parecem em nada.

O authorization code é o primeiro em que as pessoas tropeçam. O LinkedIn escreve que "the authorization code has a 30-minute lifespan and must be used immediately," e que, se ele expirar, "you must repeat all of the previous steps to request another authorization code."

O token de duas pernas é outro tipo de surpresa. A página de client credentials do LinkedIn diz "The access token has a 30-minute lifespan and must be used immediately," e seu exemplo devolve "expires_in": "1800" como string entre aspas em vez do inteiro que o fluxo de três pernas devolve. Duas pernas também não está disponível para as APIs de que a maioria das ferramentas de publicação precisa: "2-legged OAuth authentication is not available for Marketing APIs."

O LinkedIn te dá um refresh token?

Só se o LinkedIn tiver te aprovado para um. A página de refresh token abre com a tranca: "LinkedIn supports programmatic refresh tokens for all approved Marketing Developer Platform (MDP) partners," e a página do fluxo de authorization code repete pelo outro lado, dizendo que refresh tokens programáticos "are available for a limited set of partners."

Se o seu app não está nesse grupo, o caminho de renovação documentado pelo LinkedIn não é um grant type. É mandar o membro de volta pelo /oauth/v2/authorization. O LinkedIn descreve isso como transparente, e genuinamente pode ser, porque a tela de consentimento é pulada quando duas condições valem: "The member is still logged into www.linkedin.com" e "The member's current access token has not expired." Perca uma delas e o seu usuário vê a tela de autorização inteira de novo.

Por isso o próprio conselho do LinkedIn é renovar cedo: "Make sure your application refreshes access tokens before they expire, to avoid unnecessarily sending your application's users through the authorization process again." Um token renovado no dia 55 se renova em silêncio. Um token renovado no dia 61 não se renova de jeito nenhum.

Parceiros aprovados trocam o refresh token:

POST https://www.linkedin.com/oauth/v2/accessToken
 
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}

Quanto tempo dura o refresh token do LinkedIn?

365 dias, e o relógio nunca reinicia. O LinkedIn escreve que "access tokens are valid for 60 days and programmatic refresh tokens are valid for a year," e depois soletra a consequência que pega as pessoas: "When you use a refresh token to generate a new access token, the lifespan or Time To Live (TTL) of the refresh token remains the same as specified in the initial OAuth flow (365 days), and the new access token has a new TTL of 60 days."

O exemplo trabalhado do LinkedIn vale ler ao pé da letra:

• Dia 1: o refresh token tem 365 dias, o access token tem 60.
• Dia 59: renovar dá um access token novo de 60 dias, e o refresh token cai para 306 dias.
• Dia 360: "your access token and refresh token will both expire in 5 days (365-360=5) and you must get your application reauthorized by the member."

Ou seja, um refresh token compra cerca de seis renovações silenciosas e depois o membro tem que clicar em Allow de novo. Não há janela rolante, nem rotação de refresh token que estenda o horizonte, nem forma documentada de pedir mais.

O que o refresh_token_expires_in devolve de verdade?

Aqui o LinkedIn se contradiz, e a aritmética deixa isso óbvio. O campo é documentado como "The number of seconds remaining until the refresh token expires." A resposta de exemplo na mesma página devolve:

{
  "refresh_token_expires_in": 525600,
  "scope":"r_basicprofile"
}

525.600 segundos são 6,08 dias, o que não é um ano nem nenhum tempo de vida documentado do LinkedIn. 525.600 minutos são exatamente 365 dias. O exemplo está em minutos enquanto a descrição do campo diz segundos.

O segundo exemplo fecha o caso. Depois de uma renovação, a página do LinkedIn mostra "refresh_token_expires_in": 439200. A diferença entre os dois valores é 86.400, e 86.400 minutos são 60 dias, que é exatamente a distância descrita pelo exemplo trabalhado entre emitir um refresh token e usá-lo uma vez. Os dois valores de exemplo são coerentes como minutos e absurdos como segundos.

Trate a descrição do campo como autoritativa e os números de exemplo como deslize de documentação. Se você armazena uma expiração absoluta, calcule a partir do que a API viva te devolve, e não de qualquer uma das cifras daquela página.

O que invalida um access token do LinkedIn antes dos 60 dias?

Quatro coisas, todas documentadas.

Pedir um escopo diferente é a que surpreende desenvolvedores, porque nada quebra visivelmente até quebrar. O LinkedIn escreve: "If you request a different scope than the previously granted scope, all the previous access tokens are invalidated." Subir uma versão que adiciona uma permissão mata todos os tokens dos seus usuários atuais. A mesma página avisa à parte que "If the scope permissions are changed in your app, your users must re-authenticate."

Revogação pelo LinkedIn é a segunda, e o LinkedIn é direto ao reservá-la: "LinkedIn reserves the right to revoke Refresh Tokens or Access Tokens at any time due to technical or policy reasons. In such scenarios, the expectation from products leveraging Refresh Tokens is to fallback to the standard OAuth flow, and present the login screen to the end users."

Revogação pelo membro é a terceira. Um membro que desconecta o seu app nas configurações do LinkedIn encerra a concessão na hora.

Uma tentativa de renovação com credencial morta é a quarta, e devolve um erro específico: 400 invalid_request "The provided authorization grant or refresh token is invalid, expired or revoked". A coluna de resolução do LinkedIn oferece exatamente um remédio, "reauthenticate the member to generate the new refresh token."

Você não precisa adivinhar qual das quatro aconteceu. O POST https://www.linkedin.com/oauth/v2/introspectToken recebe o seu client_id, client_secret e o próprio token, e devolve status como revoked, expired ou active, junto de expires_at, created_at, authorized_at e auth_type. É essa a chamada a fazer quando posts agendados do LinkedIn param de funcionar para uma conta e mais ninguém.

Em que isso difere do token de 60 dias da Meta?

As duas plataformas dizem 60 dias. Quase nada mais bate.

O número da Meta é o esquisito. Sua resposta de exemplo devolve "expires_in": 5183944, que fica 56 segundos abaixo de 60 dias, e o texto da Meta é deliberadamente frouxo: "long-lived tokens last about 60 days." A Meta então acrescenta uma ressalva que o LinkedIn não faz, dizendo para você não depender do tempo de vida porque os tokens "may change without warning or expire early." O detalhamento completo está na nota sobre o token de longa duração do Facebook.

A divergência de verdade é o que você tem no fim da cadeia. A Meta deixa você derivar um token de acesso de Página a partir de um token de usuário de longa duração, e diz que esses "do not have an expiration date." O LinkedIn não publica equivalente e diz o oposto em uma única linha da seção de renovação: "To protect members' data, LinkedIn does not generate long-lived access tokens." O LinkedIn está descrevendo o próprio token de 60 dias como de curta duração.

Para quem constrói contra os dois, o formato prático é este. Na Meta você chega a uma credencial que sobrevive à sessão do membro. No LinkedIn você não chega, então o pedido de reconexão é um recurso permanente da integração e não um estado de falha, e agendar posts no LinkedIn com confiabilidade significa planejar para o dia em que o membro tem que clicar em Allow de novo.

Perguntas frequentes

Que valor o expires_in devolve para um access token do LinkedIn?

5184000 no exemplo publicado pelo LinkedIn, que são exatamente 60 dias em segundos.

Dá para estender um access token do LinkedIn além dos 60 dias?

Não. O LinkedIn emite um token novo de 60 dias, seja por refresh token se o seu app for parceiro MDP aprovado, seja mandando o membro pela autorização de novo.

Por quanto tempo vale um authorization code do LinkedIn?

30 minutos. O LinkedIn escreve que ele "must be used immediately" e que um código expirado significa repetir todos os passos anteriores.

Renovar reinicia a expiração do refresh token?

Não. O LinkedIn afirma que o TTL do refresh token "remains the same as specified in the initial OAuth flow (365 days)" não importa quantas vezes você o use.

Por que todos os seus tokens do LinkedIn pararam de funcionar de uma vez?

A causa mais provável é mudança de escopo. O LinkedIn invalida todos os access tokens concedidos antes quando o seu app pede um escopo diferente do já concedido.

Como checar se um token foi revogado ou expirou?

Chame POST https://www.linkedin.com/oauth/v2/introspectToken com as credenciais do cliente e o token. O campo status devolve revoked, expired ou active.

O que acontece quando o refresh token do LinkedIn expira junto com o access token?

O próprio exemplo do LinkedIn coloca isso no dia 360, quando faltam cinco dias tanto para o access token quanto para o refresh token. Assim que essa janela se fecha, o membro precisa passar pela autorização de novo, porque nenhum grant type consegue renovar um refresh token já expirado. A página do refresh token não documenta nenhuma forma de prorrogar o próprio refresh token.

Por que a maioria das ferramentas de postagem não pode depender do token two-legged do LinkedIn?

O token de client credentials dura só 30 minutos, e o LinkedIn o documenta como indisponível para as Marketing APIs, justo a superfície da qual dependem as ferramentas de agendamento e postagem. A resposta de exemplo até devolve expires_in como uma string entre aspas, "1800", em vez do inteiro que o fluxo three-legged retorna. Qualquer app que poste em nome de um membro precisa usar o fluxo three-legged em vez disso.

O número de 5.184.000 segundos do LinkedIn bate com a promessa de 60 dias?

Bate de forma exata. A documentação do LinkedIn afirma uma vida útil de 60 dias, e o valor de exemplo de expires_in, 5184000 segundos, equivale sem arredondamento a exatamente 60 dias. Essa precisão torna ainda mais visível, mais adiante na mesma documentação, a confusão entre minutos e segundos no campo refresh_token_expires_in.

O LinkedIn chega a emitir um token que nunca expira?

O LinkedIn não documenta nenhuma opção assim. Todo access token tem vida útil de 60 dias, e a empresa afirma diretamente que não gera access tokens de longa duração, diferente da Meta, que permite derivar de um token de usuário de longa duração um Page access token sem data de expiração.