Login and Access Tokens

Most platforms require authorization before you can access data. So you need an account if you want to access Facebook, Twitter or YouTube data. In general, you don't give your username and password to Facepager directly. You rather ask the platform to give you a special password which is called "access token" or "access key". When you login to Facebook, Twitter, Google or other services with Facepager, you will get such a token. Facepager never uses your personal credentials.

Important: In the Query Setup, credential tokens will be encoded, but they are visible in the Status View. If you ask for help, you should black out the tokens in screenshots or in the messages from the Status View to prevent data misuse. If you work on public devices, you should delete your access tokens before closing Facepager. You can set a tick at Clear settings when closing to automatically delete the tokens.

Open Authorization

The access tokens usually come from a process called Open Authorization (OAuth). OAuth is a standard for access delegation. By this users can get access to websites or applications via a third party application without giving them the passwords. Companies such as Amazon, Google, Facebook, Microsoft and Twitter commonly use this mechanism.

Generally, OAuth provides to clients a "secure delegated access" to server resources. It specifies a process for resource owners to authorize third-party access to their server resources, in case of Facepager the APIs, without sharing their credentials. Facepager is this kind of third party application. It doesn’t get any information about you. Designed to work mostly with Hypertext Transfer Protocol (HTTP), OAuth essentially allows access tokens to be used to third-party clients by an authorization server, with the approval of the resource owner.

The Access Token has not necessarily to be generated by using Facepager. For example, you can get an Access Token in the Facebook Graph API Explorer and copy it to the Facepager module of Facepager. In case you want to use this access token, login with the preregistered access first and then replace that token by pasting it into the access token field.
If you want full control about permissions, register your own App at Facebook, Google or Twitter and use the Client Id with Facepager, see the FAQ. Facebook has different kinds of access tokens for different use cases. This helps dealing with rate limits, too.

Configuring authorization

Depending on the platform there are quite different mechanisms to get an access token. Click on the settings-button in the modules to see the options.

• Facebook: Open Authorization 2.0 is used in the Facebook module. If you want to get data from a page you are admin of, enter the Page ID into the settings and login. Furthermore, you can register an own app and provide your own Client ID in the settings for full control.
• Twitter: Open Authorization 1.0 is used in the Twitter module and in the Twitter Streaming module. You can register an own app at Twitter and provide your own consumer key and consumer secret in the settings for full control.
• Twitter App-only: Twitter has different rate limits depending on whether you authorize as a user or as an app. To use application-only authentication register an app at Twitter, enter consumer key and secret in the settings and select "Twitter App-only" authentication type.
• YouTube: Open Authorization 2.0 with a Client ID and a Client Secret is used in the YouTube module. You can register your own app at Google to use your own Client ID and Client Secret. Alternatively, you can get an access token from Google. In this case, select "API key" in the authentication settings and manually enter your access token into the field.
• Amazon: Amazon uses a combination of keys to sign requests. You find these data in the Amazon Web Services console.

In the Generic module different types of authentication can be selected after clicking the Settingsbutton. Be aware that authentication is different from authorization. Put simply, authentication is the login process by which you identify yourself and get access tokens from the provider. You can think of it like getting a passport. The login procedure depends on the data you put in the authentication settings. Authorization is the procedure of getting access by using the access tokens. This is like showing a passport at the door of a club. The authorization fields are used for this procedure.

Depending on the selected option different fields need to be populated. You can even mimic the behavior of the YouTube or Twitter module if you want.

• Disable: Authentication is disabled, the authorization method should be set to "disabled" as well.
• OAuth2 stands for Open Authorization 2.0. For example, when using Google APIs you need to provide different kinds of URIs, Client ID and Client Secrets. Different endpoints further require to ask for the right scopes. After filling the fields, click "Login" to get an access token. When fetching data, the access token is send as an authorization header (e.g. "Authorization: Bearer XXXXX"). See the Google presets for an example.
• API key: If you got an access token from elsewhere (e.g. from the Graph API explorer of Facebook or from another provider) you can manually enter it into the access token field. Choose one of the options next to the access token field. Choosing "param" will append an parameter to the URL. Choosing "header" will send an header. You should define the name of the parameter or header. Typical names for parameters are "access_token" or "key" and for headers "Authorization", it depends on the API provider.
• Twitter App-only: To use application-only authentication register an app at Twitter, enter consumer key and secret in the settings and login to get an access token.
• Cookie: For scraping password protected webpages you can login to the website with Facepager and use the Cookie of the page to authorize your requests. Enter the login page URL of the website into the field Login URI and click Login. A small webbrowser window opens and after you logged in, the Cookie is transferred into the access token field. Just close the login window and make sure the authorization method is set to "header" and the name of the header is "Cookie". For clarification: no data is tranferred to the developers of Facepager. The login completely runs in the small webbrowser window in the same way you would login with Firefox or Chrome.

If you live behind a proxy, you can provide the IP-Address or hostname of the proxy. All requests for fetching data are send through the proxy. But, by now, the field is not used for authentication.

Preregistered apps

When using the Facebook, Twitter, or YouTube modules you have two options.

• Register an own app at Facebook.
  You have full control over the API but need to go through the App Review yourself.
  If you want to use this option, enter the Client ID of your registered app into the settings and login.
• Use the preregistered Facepager apps.
  If you want to use this option, leave the Client ID settings blank and login. To comply to the usage terms of the API providers we need to log users. See the privacy policy for further information.

In any case, you need to comply to laws, ethical standards and the API providers' terms. Read the terms! Be responsible!