Proofile API
OAuth Authentication
An OAuth API authentication and access delegation lets consumer applications access or modify the user's private data with his consent. OAuth is a standard authentication protocol, there are implementations available for most programming languages.
Consumer Key
The first thing that has to be done is registering your application with Proofile. You will receive a "Consumer Key" and a "Consumer Secret". This consumer secret must not be shared with anybody and must be kept confidentially.
OAuth Endpoint URL
Request Token
Authorization
Access Token
Additional Parameters and Access Rights
For the request token call, there is an optional parameter, required_access, which takes a string containing a list of access rights that are required by the customer application. If this is not presented, the user may pick which access rights that are to be granted to the consumer. The only OAuth API call that does not require any access rights is "ping". If the application for example requires the access rights "write_profile" and "write_connection", the parameter "required_access=write_profile write_connection" should be added to the request token OAuth message (url-encoded and signed of course).
The following access rights are available at the moment.
read_connection
Read access to the user's private connection data.
write_connectionWrite access for connections.
read_profileRead access to the user's private profile data.
write_profileWrite access for profile data.
Important Note for Consumer Application Developers
IMPORTANT: API calls with read access will return values respecting the visibility settings of the user, unlike normal API calls, where the data export settings are respected. Consumer application developers must respect the user's privacy and visibility settings. Consumers are monitored and will be disabled and banned from using the API if they are detected exporting private information.
The returned export_u value denotes who is allowed to view the data:
export_u = 0: only show to the user himself
export_u = 1: only show to the user's friends (if the client has a notion of friendship, that may be used)
export_u = 2: only show to logged in users
export_u = 3: show to everybody
If your application exports the data in machine readable formats (FOAF, XFN, hCard, vCard etc), it must also respect the user's export_m settings:
export_m = 0: don't export
export_m = 1: export
OAuth Requests
All OAuth signed requests have to take the first url parameter (folder) /oauth before the usual API URL. They must be signed with the tokens received from the access_token step. Parameters are encoded into the URL as for normal API calls.
Example calls
http://api.proofile.org/oauth/userid/{userid}/avatar/available
Manage Personal Tokens
Users may manage their issued tokens here.
Accepted Signature Methods
Currently only HMAC-SHA1 is accepted.
Preview
The authorization process should be fairly clear from a users point of view. First, the user has to log in to Proofile by either entering their OpenID or their username and password combination.
After logging in, the user may pick access rights to be granted to the consumer service for a limited or unlimited amount of time. The user may at any time modify or revoke access tokens that have been granted.
