Authentication | Comecero Documentation

Authentication is done using OAuth 2.0 Bearer tokens. To make a request, you must include the token in the Authorization header of the HTTP request. The token is prefixed with Bearer as shown in the example HTTP call below:

POST /api/v1/carts HTTP/1.1
Host: api.comecero.com
Authorization: Bearer secret.live.ni295MF6Fg8KFo7ak90sKqLPHlRp40UH88Ypw4Lzfx2.1447194286.1b3d252fd6
Content-Type: application/json

{ ... }

Token Types

The API has three different types of tokens, each explained below.

Secret Tokens

Secret tokens are designed for server to server communication and should be kept secret, confidential and secure. They provide a powerful access mechanism to your resources and should be treated carefully. The importance of keeping these tokens secure cannot be overstated.

A secret token can be limited in scope so that it only has access to specific resources and methods. Additionally, a secret token can have an associated expiration date. We recommend that rather than creating "super" tokens with access to all resources and methods, you create tokens for specific purposes and applications and limit the permissions associated with a token on an as-needed basis. You can change the permissions associated with a secret token at any time.

The easiest way to create a secret token is from within your account under Developer> Tokens. Alternatively, you can generate secret tokens through the API.

Limited Tokens

Limited tokens provide the ability to build incredibly powerful client-side applications for your customers / shoppers. While not exactly the same, Limited tokens are similar to the concept of a session ID in server-side applications.

Limited tokens should never be hard-coded into a client side application (except for convenience in local testing / development). Instead, client-side applications should generate a new Limited token for each user and store it in the user's cookies, thereby enabling each user to have a unique token, which allows them to read and modify resources they create (such as carts and orders). Limited tokens can be easily be generated from client-side code with a simple API call.

Limited tokens have the ability to perform a large variety of operations, but are only authorized to perform those operations against specific customer-owned resources. Anyone can obtain a limited token, but limited tokens are scoped to the user who obtains the token.

Perhaps the best way to understand the nature of limited tokens is with an example:

A user makes a request for a new limited token. No authorization or authentication is necessary to obtain a new token. This new token has very limited permissions, for example, permission to read public products from the account that issued the token. Using the token, it can browse the accounts products and use them to create a new shopping cart.

When a shopping cart is created using a Limited token, the cart is "bound" to that Limited token, so the Limited token's permissions have grown to include the ability to update that shopping cart. Naturally this does not mean it can update other shopping carts, just the cart it created. You don't need to take any action to manage these permission changes, this is all automatically handled in the background for you.

Beyond the ability to modify the cart it created (adding and removing products, adding customer details, etc.), the limited token can also submit a payment for the cart. After a successful payment, the limited token then has access to read the associated order and other associated resources (such as subscriptions, invoices, etc.).

Limited tokens are specifically designed to allow you create ecommerce applications that are 100% client-side. Client-side applications allow you to rapidly test and deploy new features, allow developers who are "mostly designers" to be incredibly productive without any assistance from back-end developers, can provide extraordinary performance and delightful user experiences.

Of course, you are not required to build client-side applications. But when you combine client-side applications with the Comecero hosting environment, you maintain full control of your application while offloading nearly all aspects of PCI compliance to us.

Limited tokens expire approximately 14 days after last access. This allows customers who start shopping sessions to return to them after long delays and continue without interruption.

Trusted Tokens

Trusted tokens are designed to be used within client-side environments, but can have all of the power that a secret token has. The primary difference between trusted tokens and secret tokens are:

• Trusted tokens cannot be created explicitly through the control panel or through the API. Instead, they are created and assigned to a user when signing in through the Comecero Sign-in page.
• Trusted tokens have a short expiration: Approximately 60 minutes after the last use, a trusted token automatically expires.
• The permissions assigned to a trusted token is directly inherited from the user to whom the trusted token is assigned. In other words, when a user signs in, they will receive a trusted token with the same level of permissions assigned to that user.

By default, a user is redirected to the Comecero Admin control panel after signing in. However, if you develop custom applications for internal users, you can register the URLs of these applications with your account and have internal users redirected to these applications after signing in via the OAuth 2.0 implicit grant specification. Upon successful sign in, the user is redirected to your application's receiver and a bearer token is included in the URL. Your application can then use this token to perform requests on behalf of the user.

The trusted token assigned to a user receives all the permissions assigned to that user. It is not possible to change the access level of a trusted token directly; any access changes must be applied to the user which will then be applied to the next trusted token assigned to that user.

Trusted tokens expire after 60 minutes of non-use. After the token is expired, the user can be directed back to the Comecero Sign-in page, and then redirected back to your application.

To redirect your users to a custom location, follow the instructions below:

1. Create the application

2. Add the OAuth 2.0 receiver URL to your account's general settings.

3. Direct your users to the following URL, replacing https://example.com with your redirect URL

https://signin.comecero.com/?redirect_uri=https://example.com

Note that the redirect URL you provide in the URL must be exactly the same as the URL provided in your account settings. If an unregistered URI is provided in the redirect_uri query string parameter, after the user successfully logs in, the sign-in page will display an error indicating that the redirect is not allowed. (Note that the error message is not shown until after successful login to prevent unauthorized parties from discovering valid redirect endpoints, but a redirect to an unregistered URI will never occur.)

Additionally, instead of registering custom redirect URLs within your account, as an alternative you can create apps from within your account (under Developer> Apps) which provide more flexibility in configuration. Apps created this way support both OAuth 2.0 implicit grant for client-side applications and authorization code grant flows for server-side applications. You can read more in Custom Applications.