BeProduct for developers

Introduction

Welcome to BeProduct API! Here you will find comprehensive information for integrating with our API endpoints. We've tried to make this documentation user-friendly, but if you have any questions, please email to our support email. If you are planning to use our API in production, take a look at our privacy policy.

Authorization

BeProduct API uses the OAuth 2.0 protocol for authorization. Every API request must contain the Authorization header or the access_token parameter with OAuth 2.0 token. Access scopes may be requested during the authorization process.

API keys and access

To gain access to the BeProduct API, please create an account on our Admin page. Once you've completed the signup process and acknowledged our terms, we will provide a client id and client secret which will be used in the OAuth flow.

REST API

The API methods are organized in the RESTful way. To access specific API method, the request token should have at least one of the scopes required by this method. Each API method operates on a certain type of resources with a defined model and produces a JSON response that contains then entity type in the kind field and an array of entities in the data field. The client can pass an additional parameter in the request, which also will be included in the response.

Re*sponse Example

{
     "id":"header_number",
     "name":"Style Number",
     "value":"S45994"
     "type":"text"
}

OAuth2

OAuth 2.0 is a protocol that lets your app request authorization to private details in a user's BeProduct account without getting their password. You'll need to register your app before getting started. A registered app is assigned a unique Client ID and Client Secret which will be used in the OAuth flow. The Client Secret should not be shared.

The OAuth Flow

BeProduct uses OAuth 2.0's authorization code grant flow to issue access tokens on behalf of users.

API Access

Applications have two fundamental ways with which they communicate with APIs – using the application identity, or delegating the user’s identity. Sometimes both ways need to be combined. OAuth2 is a protocol that allows applications to request access tokens from a security token service and use them to communicate with APIs. This reduces complexity on both the client applications as well as the APIs since authentication and authorization can be centralized.

OpenID Connect and OAuth2

OpenID Connect and OAuth2 are very similar – in fact OpenID Connect is an extension on top of OAuth2. This means that you can combine the two fundamental security concerns – authentication and API access into a single protocol – and often a single round trip to the security token service.
This is why we believe that the combination of OpenID Connect and OAuth2 is the best approach to secure modern applications for the foreseeable future. BeProduct implements these two protocols and is highly optimized to solve the typical security problems of today’s mobile, native and web applications.

Endpoints

Authorization Endpoint

(URL encoding removed for readability)

GET https://id.winks.io/ids/connect/authorize?client_id=client1&scope=openid email roles beproductDeveloper&response_type=id_token token&redirect_uri=https://myapp/callback&state=abc&nonce=xyz

Token Endpoint

(Form-encoding removed and line breaks added for readability)

POST https://id.winks.io/ids/connect/token
Authorization: Bearer <access_token>

grant_type=authorization_code&
code=hdh922&
redirect_uri=https://myapp.com/callback

UserInfo Endpoint

(Form-encoding removed and line breaks added for readability)

GET https://id.winks.io/ids/connect/userinfo
Authorization: Bearer <access_token>

HTTP/1.1 200 OK
Content-Type: application/json
{
   "sub": "248289761001",
   "preferred_username": "john.smith",
   "email": "john.smith@beproduct.com",
   "email_verified": "true",
   "userinfo": [
       "id":"1",
       "firstname":"John",
       "lastname":"Smith", 
        ...
   ]
}

Logout Endpoint

Redirecting to the logout endpoint clears the authentication session and cookie.

You can pass the following optional parameters to the endpoint:

• id_token_hint*: The id_token that the client acquired during authentication. This allows bypassing the logout confirmation screen as well as providing a post logout redirect URL
• post_logout_redirect_uri: A URI that IdentityServer can redirect to after logout (by default a link is displayed). The URI must be in the list of allowed post logout URIs for the client.

 https://id.winks.io/ids//connect/endsession?id_token_hint=...&post_logout_redirect_uri=https://myapp.com

API Methods

To use the API, you'll need to be familiar with OAuth2 and REST API principles and the mechanics of constructing requests and parsing responses.

Base URL for REST Endpoints

API Limits

BeProduct API is available in all editions of BeProduct. To use the API, you will require the BeProduct Authentication Token from your account. Please make sure that you have the permission to access the API, if you don’t have permission, please contact your BeProduct administrator.

Important Notes

• We notify BeProduct administrator if your organization exceeds the API limit.
• To optimize your API usage, get maximum 200 records with each request and insert, update or delete maximum 100 records with each request.
• Upper Limit Example: If you have purchased 10 user licenses, you are allowed 2500 requests per day. Using each of those 2500 requests, you can update maximum 100 records. That would be 2500 x 100 i.e. 250,000 records can be updated/inserted/deleted per day.
• In case, your application requires more than the upper limit, your additional API requests will not be processed. To avoid data transfer issues, please assess your API requirements well in advance. If you need any help, please contact our Support at support@beproduct.com