BeProduct API Authorization

Introduction

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.

Response Example

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

Authentication

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)

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.