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 | |
---|---|
Method |
|
Parameters |
|
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 |
|
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 | |
---|---|
Method |
|
Parameters |
|
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 | |
---|---|
Method |
|
Parameters |
|
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 "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
oauth_token=42f5733a2f4e064fd75f3f4c9ba8c2ee&oauth_token_secret=23a1312c61c777d2a6e302fcae8fb43c
Postman Sample Request / Response