OAuth 2.0 Authorization Flow

A web server application should always use the authorization code flow.  This is the most popular and the most secure of all of the authorization flows.  Once an authorization code is acquired it may be exchanged within five minutes for an access token by using the shared secret.

Authorization Code Flow Steps

  1. The developer should register their new application through the developers console. An application ID is generated automatically.

  2. This flow is initiated by redirecting the user to the authorize endpoint and passing a response_type of code along with the application ID, a space delimited list of the scopes requested, and the redirect URI. 

    POST https://api.channeladvisor.com/oauth2/authorize
    
    Content-Type: application/x-www-form-urlencoded
    Body: client_id = [application id] &
          response_type = code &
          access_type = offline &
          scope = orders inventory &
          redirect_uri = [redirect uri]

    The redirect URI must be HTTPS, and the redirect URI in this request has to match the Redirect URI entered in the Application definition in the Dev Console.

    The HTTP format of this request will be formatted as follows:

    POST /oauth2/authorize HTTP/1.1
    Host: api.channeladvisor.com
    Content-Type: application/x-www-form-urlencoded
    Cache-Control: no-cache
    
    client_id=a1bcd3efghi340j9k0lmn0op521qrstu&response_type=code&access_type=offline&scope=orders+inventory&redirect_uri=https%3A%2F%2Fwww.redirecturl.com%2Foauth2%2Fcallback

    The URL format of this request will be formatted as follows:

    POST https://api.channeladvisor.com/oauth2/authorize?
    client_id=a1bcd3efghi340j9k0lmn0op521qrstu&response_type=code&access_type=offline&scope=orders+inventory&redirect_uri=https%3A%2F%2Fwww.redirecturl.com%2Foauth2%2Fcallback
  3. The user is redirected to a grant page whereupon they are required to authenticate and grant or deny access.
  4. The server will generate a unique authorization code and return this to the redirect URI as a query string parameter. 

    https://[redirect uri]?code=[authorization code]
  5. The authorization code may be exchanged within five minutes for an access token and a refresh token.  The access code should be posted to the token endpoint along with the application ID and shared secret as the username and password for basic HTTP authentication.  The redirect_uri is provided here as an additional security measure and should match the value configured in the Developer Console and what was used when requesting the authorize endpoint above.  
    Note: For security reasons a refresh token will only ever be returned once per authorization.  Therefore, save the refresh token in a secure location. If the refresh token is lost, send the user back through the grant screen again by specifying approval_prompt = force in the authorization request.  For convenience, the grant screen will remember which profiles the user choose the last time the application requested access.

    POST https://api.channeladvisor.com/oauth2/token
    
    Authorization: Basic [application id:shared secret]
    Content-Type: application/x-www-form-urlencoded
    
    Body: grant_type = authorization_code &
          code = [authorization code] &
          redirect_uri = [redirect uri]

    The application ID and shared secret must be concatenated using a colon then RFC2045-MIME (base-64) encoded.
    For example, if the application ID is
    12345 and shared secret is abcde, they should be concatenated (12345:abcde) and then encoded (MTIzNDU6YWJjZGU=) so that the final Authorization header looks like: 

    Authorization: Basic MTIzNDU6YWJjZGU=

    The HTTP of this request will be formatted as follows:

    POST /oauth2/token HTTP/1.1
    Host: api.channeladvisor.com
    Authorization: Basic MTIzNDU6YWJjZGU=
    Content-Type: application/x-www-form-urlencoded
    Cache-Control: no-cache
    
    grant_type=authorization_code&code=z1yxw3vutsr340q9p0onm0lk521jihgf&redirect_uri=https%3A%2F%2Fwww.redirecturl.com%2Foauth2%2Fcallback

    The URL format of this request will be formatted as follows:

    POST https://api.channeladvisor.com/oauth2/token?grant_type=authorization_code&code=z1yxw3vutsr340q9p0onm0lk521jihgf&redirect_uri=https%3A%2F%2Fwww.redirecturl.com%2Foauth2%2Fcallback
  6. An access token is returned as a JSON response along with the time (in seconds) til expiration.

    {
      "access_token": [access token], 
      "token_type": "bearer", 
      "expires_in": 3600,
      "refresh_token": [refresh token]
    }

Updating the Access Token

Access tokens expire after one hour.  Use a refresh token at any time to obtain a new access token.  Even if offline access is requested again, a new refresh token will not be generated.

POST https://api.channeladvisor.com/oauth2/token

Authorization: Basic [application id:shared secret]
Content-Type: application/x-www-form-urlencoded
Body: grant_type = refresh_token &
      refresh_token = [refresh token]

The application ID and shared secret are concatenated using a colon then RFC2045-MIME encoded.  See Authorization Code Flow (step 5) for additional details.

The HTTP of this request will be formatted as follows will look like this:

POST /oauth2/token HTTP/1.1
Host: api.channeladvisor.com
Authorization: Basic MTIzNDU6YWJjZGU=
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=refresh_token&refresh_token=acCD58Efghijk1L7mn-OPq0rTqOb5oRsTUvwxyZabcD


Upon delivering the payload, a new access token is returned in response

{
  "access_token": [access token], 
  "token_type": "bearer", 
  "expires_in": 3600
}


Implicit Flow

All client side desktop, phone, or javascript applications should utilize the implicit flow.  Since a shared secret should never be compiled into these types of applications this flow does not involve an authorization code and therefore does not transmit a secret.  A single request is made and if the user authorizes access then an access token is granted.  For security reasons it is highly recommended that developers implement the anti-forgery token pattern when using this flow.

  1. The developer should register their new application through the developer console. An application ID is generated automatically. 
  2. This flow is initiated by redirecting the user to the authorize endpoint and passing a response_type of token along with the application ID, a space delimited list of the scopes requested, the redirect URI, and an anti-forgery token.

    GET https://api.channeladvisor.com/oauth2/authorize ?
        client_id = [application id] &
        response_type = token &
        scope = orders &
        redirect_uri = [redirect uri] &
        state = [anti-forgery token]

    The URL format of this request will look something like this (there will be no HTML format as this is designed to be included in the URL only):

    GET https://api.channeladvisor.com/oauth2/token?client_id=a1bcd3efghi340j9k0lmn0op521qrstu&response_type=token&scope=orders+inventory&redirect_uri=https%3A%2F%2Fwww.redirecturl.com%2Foauth2%2Fcallback&state=insertantiforgerytoken
  3. The user is redirected to a grant page whereupon they are required to authenticate and grant or deny access.
  4. An access_token is returned to the redirect URI as a query string parameter along with the time (in seconds) til expiration.

    https://[redirect uri] ? 
        access_token = [access token] & 
        token_type = Bearer & 
        expires_in = 3600 & 
        state = [anti-forgery token]
  5. Validate the returned anti-forgery token against the user’s session to prevent confused deputy security exploits such as cross-site request forgery (CSRF) and cross-site scripting (XSS).