OAuth Scopes

The OAuth scopes determine the range of permissions of an access_token. The OAuth application can perform one action or another, depending on the permissions the user provided.

The following scopes are currently available:

• personal_information: Allows the OAuth application to retrieve the name and email of the user
• personal_configuration: Allows the OAuth application to retrieve some user configuration. The information returned is the user locale, timezone and preferred date format and number separators.
• product_apis: Allows the OAuth application to perform requests to Inbenta APIs in the name of the user.

OAuth Resources

OAuth resources are the available applications that accept an OAuth access token as an authorization method.

There are two resources available: Accounts and Auth API.

Accounts OAuth resource

The Inbenta Accounts service has a specific endpoint to retrieve user information.

The amount of information that is returned in this endpoint depends on the scopes that have been accepted for the provided OAuth access token.

The following parameter can be returned:

• Without any scope
  • ID: This is a unique identifier of the user
• With the ‘personal_information’ scope:
  • Name: Full name of the user
  • Email: Email of the user
• With the ‘personal_configuration’ scope:
  • Locale: Which language has the user configured in Inbenta system
  • Timezone: Which timezone thas the user selected
  • Date format: The user-preferred date format
  • Number separators: The selected user separators for thousands and decimals

Here is an example of a response from the Accounts service, to a request for user information with both the personal_information and personal_configuration scopes:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "id": "asd98e7ead7fac8sdb7fe123",
    "name": "Michael",
    "email": "michael@test.com",
    "locale": "en",
    "numberSeparators": {
        "thousands": ".",
        "decimal": ","
    },
    "dates": {
        "format": "DD-MM-YYYY",
        "smart": "off"
    },
    "timezone": "Europe/Madrid"
} 

Auth API OAuth resource

For more information about the Auth API, see the API Authorization section

You can start an authorization process with an OAuth access token. To do this, you must request one of the following scopes when you create the OAuth access token:

• product_apis: this allows the OAuth app to perform requests to the product APIs with an OAuth access token
• km_editor_api: this allows the OAuth app to perform requests to the KM Editor API with an OAuth access token. This impersonates the user.
• reporting_api: this allows the OAuth app to perform requests to the Reporting API with an OAuth access token. This impersonates the user.

If you do not request one of these two scopes, Auth API returns a 403 Forbidden error response.

Requesting API Authorization with OAuth token

The first step is to obtain the OAuth token with the necessary scopes for the application. This is described in Getting the user authorization. 

Once you have the OAuth token you can perform the request to the Authorization API using the ‘x-oauth-token’ Bearer header:

curl --request POST \
  --url https://api.inbenta.io/v1/auth \
  --header 'content-type: application/json' \
  --header 'x-inbenta-key: yourAPIKeyValue' \
  --header 'x-oauth-token: Bearer yourOAuthTokenValue' \
  --data '{
	"secret": "yourSecretKeyValue"
   }'