EasyBib’s API allows third-parties to access all the data contained in EasyBib’s data store. Authentication is handled using OAuth2. The following descibes how to get access.

OAuth2 is a protocol that lets external apps request authorization to private details in a user’s EasyBib account without getting their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.

Registering an application

All developers need to register their application before getting started. The information can be filled as it suits, except the Redirect URL.

The redirect URL is the callback URL that EasyBib will return the the user to after successful authentication.

A registered OAuth application is assigned the following values:

  • a unique Client ID
  • a unique Client Secret

Please note: The Client Secret should not be shared.

Using an OAuth2 library

You can use any OAuth2 library for your favorite language available. For an up-to-date list of client libraries, please refer to the oauth.net website.

The advantage of using a library is that you will only have to configure the OAuth2 URLs in your client and the rest happens automatically for you.

The URLs are as follows:

  • https://id.easybib.com/oauth/authorize
  • https://id.easybib.com/oauth/token

Web Application flow

Read on only if you're either interested in OAuth2 or have to implement your own client.

1. Redirect the user to request access

GET https://id.easybib.com/oauth/authorize

This request is usually happens in the user's browser.

Parameters

  • response_type Required string

    Has to be of value code

  • client_id Required string

    The client ID you received from EasyBib when you registered.

  • redirect_uri Optional string

    URL in your app where users will be sent after authorization. See details below about redirect urls.

  • scope Optional string

    Space separated list of scopes. Default scope: USER_READ, read more about scopes

  • state Optional string

    An unguessable random string. It is used to protect against cross-site request forgery attacks.

2. EasyBib redirects back to you

If the user accepts your request, EasyBib redirects back to your redirect URL with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted.

GET https://your-site.com/authorized?code={code}&state={state}

If the user did not accept your request, EasyBib redirects back to your redirect URL with an error access_denied

GET https://your-site.com/authorized?error=access_denied&error_description=The+user+denied+access+to+your+application

Exchange this for an access token:

POST https://id.easybib.com/oauth/token

This request is done server to server:

curl -X POST \
https://id.easybib.com/oauth/token \
-d 'grant_type=authorization_code&code=...&client_id=...&client_secret=...'

Parameters

  • grant_type Required string

    Has to be value authorization_code

  • code Required string

    The code you received as a response to Step 1.

  • client_id Required string

    The client ID you received from EasyBib when you registered.

  • client_secret Required string

    The client secret you received from EasyBib when you registered.

  • redirect_uri Required string

    URL in your app where users will be sent after authorization.

Response

By default, the response will take the following form:

{
  "access_token":"3e2de69ee40b74eee3d00a07f54d2c7d7ba5efbe",
  "expires_in":3600,
  "token_type":"bearer",
  "scope":"USER_READ DATA_READ",
  "refresh_token":"c1dc1403dfddac1cab6d0a0c6f9c71da3e8b50f1"
}

3. Use the access token

The access token allows you to make requests to the API on a behalf of a user.

Parameters for GET requests

GET https://data.easybib.com/user/?access_token=...

HTTP headers for POST, PUT, DELETE and PATCH requests

POST https://data.easybib.com/projects/
  • AUTHORIZATION Required string

    Has to be value Bearer access_token

Read more about how to integrate the api in the next chapter.

4. Access token expiration

The access token has only a relatively short lifetime before it expires. This is due to it's nature as it is send openly with every request and it could be intercepted.

When you get the message:

{"error":"invalid_grant","error_description":"The access token provided has expired"}

You have to catch this and get a new access_token by using the refresh_token first.

POST https://id.easybib.com/oauth/token

Parameters

  • grant_type Required string

    Has to be value refresh_token

  • refresh_token Required string

    The refresh token you received with the first access token

  • client_id Required string

    The client ID you received from EasyBib when you registered.

  • client_secret Required string

    The client secret you received from EasyBib when you registered.

Response

The response will bring a fresh access token

{
  "access_token":"cc0d632e7be14bae03f9384accefadc1fc868b81",
  "expires_in":3600,
  "token_type":"bearer",
  "scope":"USER_READ DATA_READ"
}

With this new access token you can continue sending requests.

5. Error Responses

The OAuth2 error responses have always the same format with error defining the type of errer and error_description being more detailed about the missing requirements.

Example:

{
  "error":"invalid_grant",
  "error_description":"The access token provided has expired"
}

Possible Errors

  • invalid_request

    The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.

    Possible detailing desciptions:

    • Invalid or missing response type: Response type can be of value code (see Step 1)
    • Missing parameter: "code" is required: see Step 2
    • Missing parameter: "refresh_token" is required: see token expires
    • Authorization code doesn't exist or is invalid for the client
    • The access token was not found
    • Invalid refresh token
    • Malformed auth header: see Use the access token POST parameters
    • Only one method may be used to authenticate at a time (Auth header, GET or POST): see Use the access token POST parameters
    • When putting the token in the body, the method must be POST: see Use the access token POST parameters
    • The grant type was not specified in the request: Grant type can be of value authorization_code or refresh_token
  • invalid_grant

    The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.

    Possible detailing desciptions:

    • The access token provided is invalid
    • The access token provided has expired: see Step 4
    • Malformed token (missing "expires" or "client_id")
    • The user you requested the token for is not valid
    • An unsupported scope was requested. see Scopes
  • invalid_client

    Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).

    • No client id supplied'
    • Client credentials were not found in the headers or body
    • The client credentials are invalid
  • insufficient_scope

    • The request requires higher privileges than provided by the access token
  • invalid_uri

    • The redirect URI must not contain a fragment
  • access_denied

    • The user denied access to your application
  • invalid_scope

    The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

    • An unsupported scope was requested

Scopes

Scopes let you specify exactly what type of access you need. Scopes limit access for OAuth tokens. They do not grant any additional permission beyond that which the user already has.

The scopes the client can request an access token for are limited by the selected ones at the client registration.

For the web flow, requested scopes will be displayed to the user on the authorize form.

  • (no scope)

    The default scope(s) will be set for the token. USER_READ DATA_READ

  • USER_READ and USER_READ_WRITE

    The two scopes allow access to users data. To discover what you can request the following:

    GET https://data.easybib.com/user/
    
  • DATA_READ

    All DATA_* scopes allow access to projects, citations and comments. To discover what you can request the following:

    GET https://data.easybib.com/projects/
    
  • DATA_READ_WRITE

    Expands the DATA_READ scope for HTTP methods POST, PUT, DELETE and PATCH

© 2012-2017 Imagine Easy Solutions LLC