Data-API

 

Data-API

 

Methods

 

Hyves API User Authorization

  1. oAuth request URLs
  2. oAuth Authorize steps
    1. Obtaining an Unauthorized Request Token
    2. Obtaining User Authorization
    3. Obtaining an Access Token
1. oAuth request URLs

As suggested in the oauth specification a Service Provider defines 3 oAuth request URLs:

2. oAuth Authorize steps

As defined in the oAuth specification:

  1. Obtaining an Unauthorized Request Token (api-method: auth.requesttoken).
  2. Obtaining User Authorization (redirect client to "http://www.hyves.nl/api/authorize/?oauth_token=xxxx&oauth_callback=http%3A%2F%2Fwww.example.com%2F").
  3. Obtaining an Access Token (api-method auth.accesstoken).
2.1. Obtaining an Unauthorized Request Token

First step to let an User authenticatie for your Api application is obtaining a requesttoken. This is done by calling the api-method auth.requesttoken.
The methods that will be valid for the accesstoken that will follow from the authorization process must be defined with auth.requesttoken parameter methods.
The expiration of the accesstoken that will follow from the authorization process can be changed with the parameter expirationtype. There are 3 different types:

  • default - default expiration time: 1 hour
  • infinite - 'infinite' expiration time: 100 years
  • user - user can select expiration date during authorization

expirationtype: default

This is the default expirationtype and not required to add as parameter. Accesstoken's when using expirationtype default will be valid for 1 hour.

expirationtype: infinite

Infinite accesstoken's are valid for 2 years. But the user will need to check the "Remember my settings for this website." during authorization, otherwise the expirationtype will be reset to default.

expirationtype: user

This expirationtype will give the control of the expiration to the user, during authorization the user can select the expiration. The user will be able to choose between the following expiration time span's:

  • 30 minutes
  • 1 hour
  • 1 day
  • 1 week
  • 1 month

Newly created requesttokens are valid for 10 minutes.

2.2. Obtaining User Authorization

A requesttoken itself is quite useless, it needs to be authenticated by an User. This is done at a webpage at the Service Provider (Hyves).
The Consumer redirects the User to the Authorize url at the Service Provider. This page is also usable in popups (the page will scale with the size of the popup).
Authorized requesttokens are valid for 2 minutes.

Authorize url:

http://www.hyves.nl/api/authorize/

Mobile variant:

http://www.hyves.nl/mini/api/authorize/

The Authorize url expects for following parameters:

  • oauth_token - the unauthorized requesttoken, required.
  • oauth_callback - the callback url whereto redirect after, optional.

oauth_token

This is the unauthorized requesttoken, just retrieved using the api-method auth.requesttoken.

oauth_callback

An urlencoded web-address where the User will be redirected to after accepting or declining the authentication request.

The parameter will look like this:

  • Web-address:

http://www.consumer.com/authorized?identification=abcdef

  • Parameter:

http%3A%2F%2Fwww.consumer.com%2Fauthorized%3Fidentification%3Dabcdef

The User will be redirected to the following url afterwards:

http://www.consumer.com/authorized?identification=abcdef&oauth_token=xxxxxxxxx

2.3 Obtaining an Access Token

An authorized requesttoken must be exchanged for an accesstoken before it can be used for api-calls. This is done by the api-method auth.accesstoken.
To the output is exists of the new oauth_token and oauth_token_secret, as well with some additional information like authenticated userid, allowed methods and expiration.