Authentication
The Figg API utilizes OAuth 2.0 to provide Authentication for the Figg API. The first requirement is that you have a client_id and client_secret. The client_id and client_secret are used to request access tokens that will be provided to the API and authorizes your application to perform various actions on various resources.
The client_id and client_secret assigned to your application allow your application to support different OAuth 2.0 flows. Below is a table that lists the application types and the flows that they support:
| Application Type | OAuth 2.0 Flow/Grant |
|---|---|
| PUBLIC | Supports authorization_code and implicit. |
| PARTNER | Supports authorization_code, implicit, and client_credentials flow. |
To better understand the above flows and when they would be used we recommend the following presentation on SlideShare. Another article by the same author is on his website.
OAuth 2.0 is a simpler version of OAuth that is designed to avoid some of the complexity of client implementation by removing the requirements around generating signatures, nonces etc. As a tradeoff/side effect it is necessary to use SSL for any cases where an access token or client secrets are transmitted.
Protecting your client_id and client_secret
Please note that you should never share or expose your client_secret to end users or with other partners. The client_secret should only ever need to be sent between your application and Figg. Also note that a client_secret should never be compiled into a mobile application as these applications can be decompiled.
Scopes
Not all applications are created equal. Given the nature of Figg and the fact that it deals with credit card data in some cases we felt it necessary to prevent clients from being able to access certain details of a user's account. The reality is that even in the event that applications are scoped to allow, for example, listing a user's credit cards this data would be of little use to a 3rd party because we will never expose (and actually aren't even capable of) showing a user's full credit card information.
That being said all non-partner applications are restricted from accessing the cards_read and cards_write scopes.
Scopeless Access
Some of the API endpoints DO NOT require an access token and only require a client_id. In particular, these endpoints are typically venue endpoints. It should be noted as well that some of the scopeless access endpoints will still allow you to pass an access_token and this will only be done when you WANT to emulate an acting user. The reason to emulate an "acting user" is to prevent some of the anonymization that will happen to certain user accounts when their privacy is restricted. That being said there are some user's who simply have their privacy set to not allow ANY user to view their account data and in this case anonymization is inevitable.
Partner (client_credentials) Access
If you've been paying attention you will notice that one of the grant types for partners is client_credentials. This kind of access can be used to perform userless access but is also used along with a userToken to allow the partner to perform activities as though the userToken user is the actual acting user. That being said the only user's that may be provided with a userToken are those user's that have been signed up by the partner through the user signup api. The userToken parameter is expected to be the email address of the user that was signed up.
Access token expiration
All client applications should be prepared to handle token expiration. Currently, only authorization_code credentials will not expire (this may change in the future). Figg does not currently employ the use of a refresh token and instead advises clients to be prepared for token expiration responses and to attempt to re-request access tokens. If the application is still permitted access to the resource then the system will issue a new token to the application otherwise an error will be returned.
client_id on all requests
Although not necessary in OAuth 2.0 Figg requires that EVERY request have the client_id on the query string.