Tokens de acesso

Um token de acesso é uma cadeia de caracteres opaca que identifica um usuário, aplicativo ou Página. Ele pode ser usado pelo aplicativo para fazer chamadas da Graph API. Quando alguém se conecta a um aplicativo usando o Login do Facebook e aprova a solicitação de permissão, o aplicativo recebe um token de acesso temporário e seguro às APIs do Facebook. Há diversos métodos que podem ser utilizados para obter tokens de acesso.

Devido a uma alteração na versão 4.0 da Graph API, um pequeno subconjunto de tokens de acesso de usuários não é mais válido. Qualquer solicitação de API feita com esses tokens falhará. Se o seu aplicativo tiver sido afetado, você receberá um alerta de desenvolvimento. Consulte o ponto de extremidade /token_deprecation_check para ver se algum dos seus tokens de acesso de usuário foi afetado. Usuários com tokens de acesso invalidados precisarão de uma nova autenticação. Esta alteração afetará todas as versões em 29 de outubro de 2019. Veja o Log de alterações da Graph API para saber mais informações.

O token inclui informações sobre quando o token expirará e qual aplicativo gerou o token. Devido às verificações de privacidade, a maioria das chamadas de API no Facebook precisa incluir um token de acesso. Existem diferentes tipos de tokens de acesso para respaldar diferentes casos de uso:

Tipo de token de acessoDescrição

Token de acesso de usuário

Esse tipo de token de acesso é necessário em todos os momentos que o aplicativo chama uma API para ler, modificar ou gravar dados do Facebook de uma pessoa específica em seu nome. Tokens de acesso de usuário são obtidos por meio de uma caixa de diálogo Login e precisam da permissão da pessoa para que seu aplicativo obtenha um.

Token de acesso do aplicativo

Esse tipo de token de acesso é necessário para modificar e ler configurações de aplicativos. Também pode ser usado para publicar ações de Open Graph. Ele é gerado usando um segredo acordado previamente entre o aplicativo e o Facebook, e é então usado durante as chamadas que alteram as configurações de todo o aplicativo. Você obtém um token de acesso do aplicativo por meio de uma chamada de servidor para servidor.

Token de acesso à Página

Esse tipo de token de acesso é semelhante aos tokens de acesso de usuário, mas fornecem permissão para APIs que leem, escrevem ou modificam os dados pertencentes a uma Página do Facebook. Para obter um token de acesso à Página, é necessário obter um token de acesso de usuário e pedir a pages_show_list ou a permissão manage_pages. Depois que você tiver o token de acesso de usuário, poderá então obter o token de acesso à Página por meio da Graph API.

Token de cliente

O token de cliente é um identificador que você pode incorporar em aplicativos para desktop e binários móveis nativos para identificar o seu aplicativo. O token de cliente não se destina a ser um identificador secreto porque é incorporado em aplicativos. O token de cliente é usado para acessar as APIs de nível de aplicativo, mas apenas um subconjunto muito limitado. O token de cliente é encontrado no painel de seu aplicativo. Como o token de cliente é usado raramente, não falaremos sobre ele neste documento. Esse assunto é abordado por qualquer documentação sobre a API que usa o token de cliente.

Tokens de acesso de usuário

Embora cada plataforma gere tokens de acesso por meio de diferentes APIs, todas as plataformas seguem a estratégia básica para obter um token de usuário:

Tokens de curto prazo e de longo prazo

Os tokens de acesso de usuário existem em duas formas: tokens de curta duração e tokens de longa duração. Tokens de curta duração têm normalmente uma vida útil de cerca de uma ou duas horas, enquanto tokens de longa duração têm normalmente uma vida útil de cerca de 60 dias. Não dependa desses períodos de vida útil permanecerem iguais, pois eles podem ser alterados sem aviso ou expirar antes. Veja mais sob como lidar com erros.

Os tokens de acesso gerados por meio de login da Web são tokens de curta duração, mas você pode convertê-los em tokens de longa duração fazendo uma chamada de API do lado do servidor, juntamente com a chave secreta do aplicativo.

Aplicativos para celular que usam SDKs do Facebook para iOS e Android adquirem tokens de longa duração por padrão.

Aplicativos com Acesso padrão à API de Marketing do Facebook, ao usar tokens de longa duração, receberão tokens de longa duração que não têm tempo de expiração. Esses tokens ainda estão sujeitos à invalidação por outras razões, mas não expirarão exclusivamente com base no tempo. Isso também é verdade sobre os tokens de acesso para Usuários do Sistema no Gerenciador de Negócios.

Tokens são portáteis

É importante saber que os tokens de acesso são portáteis. Uma vez que você tem um token de acesso, é possível usá-lo para fazer chamadas de um cliente móvel, um navegador da web ou de seu servidor para servidores do Facebook. Se um token é obtido em um cliente, você pode enviar esse token para o seu servidor e usá-lo em chamadas de servidor para servidor. Se um token é obtido por meio de uma chamada de servidor, também é possível enviar o token para um cliente e, em seguida, fazer as chamadas a partir do cliente.

Mover tokens entre o seu cliente e o servidor deve ser feito de forma segura, via HTTPS, para garantir a segurança das contas das pessoas. Leia mais sobre as implicações de mover tokens entre seus clientes e seu servidor.

Plataformas diferentes têm diferentes métodos para iniciar esse processo e incluem funcionalidades para gerenciar tokens de acesso em nome do desenvolvedor e permissões concedidas pelas pessoas:

Android

Os SDKs do Facebook para Android gerenciam automaticamente tokens de acesso de usuário por meio da classe com.facebook.AccessToken. Você pode aprender mais sobre como obter um token de acesso de usuário implementando o Login do Facebook para Android. Você pode recuperar o token de acesso do usuário ao inspecionar Session.getCurrentAccessToken.

Exemplo de código

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    accessToken = AccessToken.getCurrentAccessToken();
}

iOS

Os SDKs do Facebook para iOS gerenciam automaticamente tokens de acesso de usuário por meio da classe FBSDKAccessToken. Você pode aprender mais sobre como obter um token de acesso de usuário implementando o Login do Facebook para iOS. Você pode recuperar o token de acesso inspecionando FBSDKAccessToken.currentAccessToken.

Exemplo de código

- (void)viewDidLoad
{
  [super viewDidLoad];
  NSString *accessToken = [FBSDKAccessToken currentAccessToken];
}

Javascript

O SDK do Facebook para JavaScript obtém e mantém tokens de acesso de usuário automaticamente em cookies de navegador. Você pode recuperar o token de acesso de usuário fazendo uma chamada para FB.getAuthResponse que inclui uma propriedade accessToken dentro da resposta.

Exemplo de código

FB.getLoginStatus(function(response) {
  if (response.status === 'connected') {
    var accessToken = response.authResponse.accessToken;
  } 
} );

Web (sem JavaScript)

Quando você criar um aplicativo da web sem SDK do Facebook para JavaScript, será preciso gerar um token de acesso durante as etapas descritas neste documento.

Tokens de acesso do aplicativo

Os tokens de acesso do aplicativo são usados​ para fazer solicitações para APIs do Facebook em nome de um aplicativo, em vez de um usuário. Pode ser usado para modificar os parâmetros de seu aplicativo, criar e gerenciar usuários de teste ou ler informações de seus aplicativos.

Limitações

Alguns dados de usuário, que normalmente seriam visíveis para um aplicativo fazendo uma solicitação com um token de acesso de usuário, nem sempre ficarão visíveis com um token de acesso do aplicativo. Se você está lendo os dados do usuário e utilizando-os em seu aplicativo, é preciso usar um token de acesso de usuário em vez de um token de acesso do aplicativo.

Tokens de acesso do aplicativo são considerados inseguros se o seu aplicativo está definido para Native/Desktop nas Configurações Avançadas de seu Painel de Aplicativos e, portanto, não funcionarão com chamadas de API. Isso ocorre porque supomos que os aplicativos nativos ou para desktop terão a chave secreta do aplicativo embutida em algum lugar (e, portanto, o token de acesso do aplicativo gerado usando esse segredo não é seguro).

Como gerar um token de acesso do aplicativo

Para gerar um token de acesso do aplicativo, você precisará:

Exemplo de código

curl -X GET "https://graph.facebook.com/oauth/access_token ?client_id={your-app-id} &client_secret={your-app-secret} &grant_type=client_credentials" 

Essa chamada retornará um token de acesso do aplicativo que pode ser usado no lugar de um token de acesso de usuário para fazer chamadas de API como mencionado acima. Mais uma vez, para a segurança, o token de acesso do aplicativo nunca deve ser codificado em código do lado do cliente. Isso concederia a todas as pessoas que carregassem sua página da Web ou descompilassem seu aplicativo acesso total ao seu segredo do aplicativo e, portanto, a capacidade de modificar seu aplicativo. Isso implica que, na maior parte do tempo, você estará usando tokens de acesso do aplicativo apenas em chamadas de servidor para servidor.

Observe que, por esse pedido usar a chave secreta do aplicativo, ele nunca deve ser feito no código do lado do cliente ou em um binário do aplicativo que possa ser descompilado. É importante que a chave secreta do aplicativo nunca seja compartilhado com ninguém. Portanto, essa chamada de API só deve ser feita usando o código do lado do servidor.

Há um outro método para fazer chamadas para a Graph API que não requer o uso de um token de acesso do aplicativo gerado. Basta passar o ID e a chave secreta de seu aplicativo como o parâmetro access_token ao fazer uma chamada:

curl -i -X GET "https://graph.facebook.com/{api-endpoint}&access_token={your-app_id}|{your-app_secret}" 

Para escolher entre usar um token de acesso gerado ou esse método, você precisa considerar o local onde ocultou a chave secreta do aplicativo.

Tokens de acesso à Página

Tokens de acesso à Página são usados em chamadas da Graph API para gerenciar Páginas do Facebook. Para gerar um token de acesso à Página, um administrador da página deve conceder uma pages_show_list ou uma permissão manage_pages. Quando a permissão for concedida, você poderá recuperar o token de acesso à Página usando um token de acesso do usuário com as permissões necessárias.

Exemplo de código

curl -i -X GET "https://graph.facebook.com/{your-user-id}/accounts&access_token={user-access-token} 

Essa ação retorna uma lista de Páginas em que você tem uma função e informações de cada uma, como a categoria delas, as permissões específicas que você tem em cada uma e o token de acesso à Página.

{
  "data": [
    {
      "access_token": "EAACEdE...",
      "category": "Brand",
      "category_list": [
        {
          "id": "1605186416478696",
          "name": "Brand"
        }
      ],
      "name": "Ash Cat Page",
      "id": "1353269864728879",
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    },
    {
      "access_token": "EAACEdE...",
      "category": "Pet Groomer",
      "category_list": [
        {
          "id": "163003840417682",
          "name": "Pet Groomer"
        },
        {
          "id": "2632",
          "name": "Pet"
        }
      ],
      "name": "Unofficial: Tigger the Cat",
      "id": "1755847768034402",
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT"
      ]
    }
  ]
}

Com um token de acesso à Página, você pode realizar chamadas à API em nome de uma Página. Por exemplo, você pode postar uma atualização de status para uma Página (em vez de postar na Linha do Tempo do usuário) ou ler os dados de Informações da Página.

Tokens de acesso à Página são únicos para cada Página, administrador e aplicativo.

Duração do token de acesso

Espere mudanças nas durações de todos os tipos de tokens de acesso ao longo do tempo, à medida que o Facebook fizer alterações no que está armazenado neles e em como são codificados. Você pode esperar que eles aumentem e diminuam com o tempo. Use um tipo de dado de duração variável sem um tamanho máximo específico para armazenar tokens de acesso.

Saiba mais