To access the BellaDati API, your client application needs to authenticate the user through the OAuth protocol. You can find more information about how to use OAuth in the OAuth guide.

As part of the regular OAuth protocol, the user is required to log in to BellaDati in their web browser. This way, client applications do not need to take responsibility for their users' credentials, reducing the risk of attackers being able to intercept login data. If using a web browser is not an option for your client workflow, you may instead use the xAuth variant described at the bottom of this document.

On this page:

POST /oauth/requestToken - Obtaining a Request Token

Description

In the first step of the authentication process, the client application obtains a request token to use during the remaining steps. This method corresponds to Obtaining an Unauthorized Request Token in the OAuth Core 1.0 specification.

Request Structure

URL

https://service.belladati.com/oauth/requestToken

Method

POST

Parameters

  • oauth_consumer_key: Your account's consumer key. To configure it, please visit your domain settings page.
  • oauth_nonce : A random string, uniquely generated for each request to prevent replay attacks.
  • oauth_timestamp : The current timestamp.
  • oauth_callback: (optional) Callback to redirect to after authorization is complete

Returns

A request token and the corresponding request token secret in URL encoding. This token/secret pair is later used to complete the authentication process and obtain an access token. It cannot be used for any other API calls.

Sample Request / Response

curl -d "oauth_consumer_key=myKey&oauth_nonce=7S0blJDv0G2g2iDoNM0QEMhcPPDahnHc&oauth_timestamp=1376571988" https://service.belladati.com/oauth/requestToken

Postman Sample Request / Response


oauth_token=mh7an9dkrg59&oauth_token_secret=b9q1n5il4lcc

Authorizing the Request Token

Description

After your client application has received a request token, the user needs to authorize the token for the application to gain access to the API. This is done in the user's web browser.

If your client is a web application, you can configure the CallBack URL on the domain settings page to point to your application. After successfully authorizing the request token, BellaDati will use this URL to redirect the user back to your application.

Request Structure

URL

https://service.belladati.com/authorizeRequestToken?oauth_token=requestToken&oauth_consumer_key=consumerKey&callbackUrl=http://your-server.com (open in the user's web browser)

Parameters

  • oauth_consumer_key: Your account's consumer key. To configure it, please visit your domain settings page.
  • oauth_token : The request token obtained in the previous step.
  • callbackUrl: (optional) Callback to redirect to after authorization is complete

Returns

After successful login, the request token is authorized. If a Callback URL is was set or defined on the domain settings page, the user is redirected to that page.


POST /oauth/accessToken - Obtaining an Access Token

Description

This step exchanges the authorized request token for an access token. You can subsequently use the access token to access the BellaDati API. This method corresponds to Obtaining an Access Token from the OAuth Core 1.0 specification.

Please make sure that:

  • The request token has been obtained using the same consumer key.
  • The request token has never been exchanged for an access token before.

Request Structure

URL

https://service.belladati.com/oauth/accessToken

Method

POST

Parameters

  • oauth_consumer_key: The consumer key.
  • oauth_nonce : A random string, uniquely generated for each request to prevent replay attacks.
  • oauth_timestamp : The current timestamp.
  • oauth_token : The authorized request token received in step 1 and authorized in step 2.

Returns

An access token and the corresponding access token secret in URL encoding. This token can now be used to make API calls.

Sample Request / Response

curl -d "oauth_token=mh7an9dkrg59&oauth_consumer_key=myKey&oauth_nonce=7S0blJDv0G2g2iDoNM0QEMhcPPDahnHc&oauth_timestamp=1376571988" https://service.belladati.com/oauth/accessToken

oauth_token_secret=08evn5ieuz84&oauth_token=nd7an9eba41c

Authentication without a Web Browser

Description

If your authentication workflow doesn't allow using a web browser to log in to BellaDati, you can use the xAuth protocol variant to obtain an access token in one step. The downside is that your client application will have to deal with user credentials directly and must ensure they are handled in a secure way.

xAuth access is restricted to domains for which this feature has been explicitly enabled. If it's not possible to use the regular OAuth workflow with your application you can enable xAuth in your domain settings.

To use xAuth with BellaDati On-Premise, we recommend to use SSL.

Request Structure

URL

https://service.belladati.com/oauth/accessToken

Method

POST

Parameters

  • oauth_consumer_key: The consumer key.
  • oauth_nonce : A random string, uniquely generated for each request to prevent replay attacks.
  • oauth_timestamp : The current timestamp.

  • x_auth_username : The user trying to authenticate. If "Allow login with email" is enabled, user's email can be used here.(warning) Should be stored securely in your app

  • x_auth_password : The user's password.    (warning) Should be stored securely in your app

Returns

An access token and the corresponding access token secret in URL encoding. This token can now be used to make API calls.

Sample Request / Response

Use curl command and generate time stemp using `date +%s` command
curl -d "x_auth_username=user@belladati.com&x_auth_password=password&oauth_consumer_key=myKey&oauth_nonce=7S0blJDv0G2g2iDoNM0QEMhcPPDahnHc&oauth_timestamp=
`date +%s`" https://service.belladati.com/oauth/accessToken
xAuth option will return oauth_token and oauth_token_secret
oauth_token=42f5733a2f4e064fd75f3f4c9ba8c2ee&oauth_token_secret=23a1312c61c777d2a6e302fcae8fb43c


Postman Sample Request / Response

 

  • No labels