Tokens de acesso

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.

Veja uma lista de seus tokens de acesso e informações de depuração de cada token na ferramenta Token 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. Tokens de acesso são obtidos por meio de uma série de métodos, que serão abordados mais adiante neste documento. 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 acesso Descrição

Token de acesso de usuário

O token de usuário é o tipo de token mais comumente usado. 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 as configurações do aplicativo. Também pode ser usado para publicar ações do 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

Esses tokens de acesso são semelhantes aos tokens de acesso de usuário, exceto pelo fato de fornecerem 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 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.

Como gerar tokens de acesso

Tokens de acesso de usuário

Tokens de acesso do aplicativo

Tokens de acesso à página


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:

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:

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.

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.

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.

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.

Exemplos de código

Android

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

iOS

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

JavaScript (Web)

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

Tokens de curto prazo e tokens 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 móveis 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

Um aspecto importante para entender sobre tokens de acesso é que eles 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.

Tokens de acesso do aplicativo

Tokens de acesso de aplicativos 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 que está fazendo a solicitação com um token de acesso de usuário nem sempre sã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 de aplicativo

Para gerar um token de acesso do aplicativo, você precisa fazer uma chamada para a Graph API:

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 de 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, esta 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 do aplicativo como o parâmetro access_token quando você fizer uma chamada:

curl -X GET "https://graph.facebook.com/your-endpoint?key=value&access_token=your-app_id|your-app_secret"    

A escolha de usar um token de acesso gerado versus esse método depende de onde você escondeu a chave secreta do aplicativo.

Tokens de acesso de 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 permissão estendida chamada manage_pages. Quando essa 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 e a seguinte solicitação da Graph API:

GET /me/accounts HTTP/1.1
Host: graph.facebook.com

Essa ação retorna uma lista de páginas que a pessoa administra, junto com outras informações, como a categoria da Página, as permissões que o administrador tem para essa Página e o token de acesso à página:

{
  "data": [
    {
      "category": "Product/service",
      "name": "Sample Page",
      "access_token": "{access-token}",
      "id": "1234567890",
      "perms": [
        "ADMINISTER",
        "EDIT_PROFILE",
        "CREATE_CONTENT",
        "MODERATE_CONTENT",
        "CREATE_ADS",
        "BASIC_ADMIN"
      ]
    }, 
}

Com um token de acesso à página, você pode realizar chamadas de 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.

Administradores da Página desempenham funções diferentes, que são indicadas pela matriz perms retornada, conforme o exemplo acima. A funcionalidade disponível para eles é decidida com base nos valores de perms, que são descritos em Tokens e funções.