OAuth 2.0 Introduction
All requests to the Sell API must be authenticated and must include a valid access token. The Sell API utilizes the industry-standard OAuth 2.0 protocol.
The greatest benefits of the OAuth protocol are its security and developer simplicity. Before we dive into the details and advantages of OAuth 2.0, we need to introduce some OAuth 2.0 nomenclature:
- Resource owner - Any end-user within your account, who is capable of granting protected resource access to the client.
- Protected resource - e.g. deals, contacts, leads etc.
- Resource servers - The server hosting the protected resources. In this case, the Sell servers.
- Client - An application that makes protected resource requests to resource servers on your behalf, e.g. a server or a browser.
- Authorization server - The server that issues tokens to the Client. In this case, the Sell Authorization Server.
- Access Token - Credentials provided by the authorization server that provide access to Protected Resources.
- Refresh Token - Credentials used to obtain a new Access Token when the current access token expires.
OAuth advantages:
- The API does not require you to disclose credentials to clients.
- You can revoke the consumer's access to the client application at any time.
- If the client's identity store is hacked, no credentials will be exposed, as you can simply issue expirable access tokens to individual applications.
- If a site's access token and consumer secret are compromised, then you or a resource owner can revoke them.
- You can issue scoped access to your account, which can be totally different for each client application.
Application Registration
In order to make any call to the Sell API, and to request your OAuth 2.0 access token, you need to register an application. Registered OAuth applications are assigned a unique Client ID (client_id) and a unique Client Secret (client_secret). Make sure to store the Client Secret securely.
You can learn how to authenticate this application at Client Authentication.
Notice Only users with administration management privileges can register applications.
Authentication Workflow
We support two types of applications, Single-User and Multi-User applications, described in detail in the subsections below.
Sell Authorization Server allows you to use OAuth 2.0 via one of four flows:
- Authorization Code Grant - use this flow if you want to authorize a web application.
- Implicit Grant - use this flow if you want to authorize a user-agent, a desktop or a mobile application.
- Resource Owner Password Credentials Grant - use this flow if you want to authenticate directly via Sell API using resource owner's password credentials.
- Refresh Token Grant - use this flow to renew an access token when the current one expires.
Notice We may introduce additional authentication flows in the future.
Single-User Applications
The Single-User applications workflow is a simplified workflow, where you expect a single user to use your application. You can generate any number of access tokens with an unlimited lifetime and an individual scope via the Application dashboard. All requests with that special access token act on behalf of the owner of the client application, and follow the same rules as ordinary access tokens when accessing resource servers. As there is no need to regenerate the access token dynamically, you can store it in your application configuration or in a secure data store. This workflow is very similar to widely-used API key workflows.
Notice Only users with administration management privileges can generate infinite lifetime access tokens.
Multi-User Application
The Multi-User applications workflow is used by client applications where you need an access token for each user in your account. This is the preferred method of integration with Sell, as the application acts on behalf of the resource owner who granted authorization.
Learn more about different types of supported ways of granting authorization via OAuth 2.0 protocol at OAuth Requests
Make OAuth 2.0 call
To access protected resources, the resource owner needs to supply an access token in a format described in the industry-standard OAuth 2.0: Bearer Token.
You can learn how to request a protected resource at Accessing Protected Resources.
Access Token Expiration
Each issued access token has a finite lifetime. The Sell Authorization Server, based on resource owner credentials, provides you with an access_token with the lifetime expires_in (in seconds) and refresh_token (without expiration time).
Requests with an expired access token will be rejected with 401 status code. You need to use the Refresh Token credentials in order to obtain a new Access Token. Refresh Tokens are never sent to Resource Servers. They are intended to be used by the Authorization Server.
For Single-User applications, access tokens generated via dashboard have infinite lifetime. Access tokens obtained via the token endpoint in the OAuth 2.0 Multi-User Application flow, have a finite lifetime set to one hour. Both access token types can be easily revoked.
Learn more about refreshing access tokens at Refreshing an Access Token.
Scopes
Each access token is tagged with permission scopes. Scopes control whether the presented credentials allow to perform requested call to the resource server.
For the authorization code and implicit flows, they are displayed to the resource owner on the authorization form.
Supported Scopes
| Name | Description |
|---|---|
read | Grant read-only access to all your data, except for the account and user info. |
write | Grant write-only access to all your data, except for the account and user info. |
profile | Grant read-only access to the account and users info only. |
Security
Make sure that all requests to the Sell API are made over SSL (https:// not http://).
Sell API supports OAuth 2.0 Token Revocation. You can perform a revocation request in order to notify the Authorization Server. When revocation was requested, the access token will no longer work.
Learn more how to revoke a token at Token Revocation.
Notice Client credentials and access tokens can be easily revoked and recreated at will.
OAuth Endpoints
Sell API provide the following OAuth 2.0 endpoints.
| Endpoint | Description |
|---|---|
/oauth2/authorize | Authorization endpoint. |
/oauth2/token | Token endpoint. |
/oauth2/revoke | Token revocation endpoint. |
/oauth2/token/info | Token validation endpoint. |
You can find description of all the endpoints and its parameters at OAuth 2.0 reference.