Authentication

HTTP “Basic” Authentication

This authentication method requires API access to be enabled (it is disabled by default). You must be the iScriba account owner to enable the API.

When you connect to to your iScriba account with the account owner, you have access to the “API settings” section inside the “Configuration” section. From this section you can choose to enable or disable the API.

With this authentication mode, all requests must include your username and password encoded in Base64.

cURL request example:

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X GET https://#{subdomain}.iscriba.com/api/#{arguments}

Top

---

OAuth 2.0 Authentication

If you develop an application that connects to the iScriba API, we ask that you use authentication via OAuth 2.0. This allows us to monitor the use of the API in your applications while maintaining our users’ data safe. This is a standard used by many API providers, such as the Facebook API “Graph API”. In addition, only authentication via OAuth 2.0 allows access to the API even if the account owner has not enabled it.

If you have had bad experiences with OAuth 1.0, don’t worry, the new version is radically easier to use.

1. Registration

Start by creating a developer account and reference your application to get your set of credentials. This set of credentials is composed of two keys: “CLIENT ID” and “CLIENT SECRET”.

Knowing that each set of credentials is linked to a particular URL, you should consider creating two set of credentials: one for your development server and one for your production server.

2. Get an access authorization

There are three ways to obtain an access authorization.

Application hosted on a server

• Redirect users wishing to authenticate to the following URL: https://secure.iscriba.com/oauth2/authenticate?client_id=#{client_id}&response_type=code&redirect_uri=#{redirect_uri}
• If the user accepts, he will be redirected to the following URL: https://#{redirect_uri}/?code=#{code}
• Your server will then do the following request: https://secure.iscriba.com/oauth2/access_token?client_id=#{client_id}&client_secret=#{client_secret}&grant_type=authorization_code&redirect_uri=#{redirect_uri}&code=#{code}
• The response will be in JSON format: { access_token: #{access_token} }
• Save this access token for the user in your database.

Purely AJAX application

• Redirect users wishing to authenticate to the following URL: https://secure.iscriba.com/oauth2/authenticate?client_id=#{client_id}&response_type=token&redirect_uri=#{redirect_uri}
• If the user accepts, he will be redirected to the following URL: https://#{redirect_uri}/#code=#{code}

Mobile or client-side application

(Android Java, iOS, Objective-C, etc…)

• If you have a server that communicates with your application, we strongly recommend using the “application hosted on a server” method described above, for example in an integrated browser. You will automatically get the mobile interface.
• If you do not have server-side code, you can embed a web browser and using the “purely AJAX application” method described above. You can then retrieve the authorization code in the browser and close it.
• An alternative to the above method is to use the “application hosted on a server” method and an external browser but redirect the user to a customized URI handler that returns to your application.

3. Make requests

Once you have an access token, you have three options to authenticate your requests:

1. include the string: ?access_token=#{access_token} in all your requests on the API. For example:

   curl -H 'User-Agent: #{user_agent}'\
   -X GET https://#{subdomain}.iscriba.com/api/#{arguments}?access_token=#{access_token}
   

2. include an “access_token” field that you’ll send via POST

3. include the HTTP header “Authorization” in the following form: “Authorization: OAuth2 #{access_token}”. For example:

   curl -H 'User-Agent: #{user_agent}'\
   -H "Authorization: OAuth2 #{access_token}"\
   -X GET https://#{subdomain}.iscriba.com/api/#{arguments}
   

Notes

You may encounter a problem when developing an application on Android because we use an SSL certificate of Wildcard type. For more information see the following response on Stack Overflow: http://stackoverflow.com/questions/3135679/android-httpclient-hostname-in-certificate-didnt-match-example-com-exa

Although while we do not currently expire OAuth access tokens, you should prepare for this possibility in the future. You must also develop keeping in mind the fact that the user can revoke the access token at any time from the iScriba web interface.

Top

---