Connect REST API Developer Guide

Connect REST API Developer Guide
Introduction
When to Use Connect REST API
Connect REST API Architecture
Connect REST API Rate Limits
Build the Resource URL
Send HTTP Requests
HTTP Request Flow and a Response Body
Inputs and Binary File Upload Examples
Wildcards
Specify Response Sizes
Response Body Encoding
Status Codes and Error Responses
OAuth and Connect REST API
Web Server OAuth Authentication Flow
User-Agent OAuth Authentication Flow
Tokens
Request Static Assets and Post Forms Directly from HTML
Use CORS to Access Salesforce Resources from Web Browsers
Quick Start
Work with Features
Examples
Resources
Request Bodies
Response Bodies
Appendices
PDF

Newer Version Available

This content describes an older version of this product. View Latest

User-Agent OAuth Authentication Flow

Typically this flow is used by mobile apps or applications that directly access the Connect REST API from JavaScript. In this flow, it is assumed that the client application can’t be trusted to store client credentials, nor the user login credentials.

Because the access token is encoded into the redirection URI, it might be exposed to the end-user and other applications residing on the computer or device.

If you are authenticating using JavaScript, we recommend calling window.location.replace(); to remove the callback from the browser’s history.

Warning

The following is the general flow. The individual step descriptions follow.

User-agent OAuth authentication flow
The following is a general description of the OAuth user-agent flow:
  1. To request authorization for a resource, the client application redirects the end user’s browser to a web page hosted on the resource owner’s authorization server. In this case, it’s the Salesforce login page.
  2. The end user logs in to Salesforce to authenticate themselves. Because the resource owner (Salesforce) hosts and the end user interacts directly with this web page, the client web application never finds out the user’s login credentials.

    If the client application is running in the browser already, the browser can be redirected. If the client application is a mobile app, a browser must be opened (such as an UIWebView in iOS). The end user uses this web page to authenticate themselves and then grant authorization to the client application.

  3. After authorization is granted, the authorization server redirects the end user’s web browser to a redirection URL. The client application can use this URL to retrieve the access and refresh tokens.
  4. The protected resources are Connect REST API resources.

Using the User-Agent Flow with Connect REST API and Salesforce

The following provides specific details for the OAuth user-agent flow when used with Salesforce and Connect REST API.
  1. Direct the client’s web browser to the page https://login.instance_name/services/oauth2/authorize, with these request parameters.
    Parameter Description
    response_type Must be token for this authentication flow
    client_id The Consumer Key value from the connected app defined for this application
    redirect_uri The Callback URL value from the connected app defined for this application
    You can also include these optional request parameters.
    Parameter Description
    display Indicates the type of web page that’s provided. Valid values are:
    • page—Full-page authorization screen. This is the default value if none is specified.
    • popup—Compact dialog optimized for modern web browser popup windows.
    • touch—mobile-optimized dialog designed for modern smartphones such as Android and iPhone.
    • mobile—mobile optimized dialog designed for older smartphones such as BlackBerry OS 5.
    scope Specifies what data your app can access. You do not have to specify any value to access Connect REST API If you specify any values, you must include the chatter_api value.
    state Specifies URL-encoded state data to be returned in the callback URL after approval.
  2. After successfully logging in, the user is asked to authorize the application. If the user has already authorized the application, this step is skipped.
  3. After Salesforce confirms that the client application is authorized, the end user’s web browser is redirected to the callback URL specified by the redirect_uri parameter, appended with the following values after the hash sign (#). This is not a query string.
    Parameters Description
    access_token Session ID that you can use for making Connect REST API requests. This session ID cannot be used in the user interface. Treat it like a user's session and diligently protect it.
    expires_in Amount of time the access token is valid, in seconds.
    refresh_token Token that can be used in the future to obtain new access tokens (sessions).

    This value is a secret. Treat it like the user's password and use appropriate measures to protect it.

    Warning

    The refresh token is only returned if the redirect URI is https://login.instance_name/services/oauth2/success or used with a custom protocol that is not HTTPS.
    These additional parameters are returned; however, they aren't used with this flow and Connect REST API.
    • instance_url
    • id
    • signature
    • issued_at
  4. If the client application is a web app, the redirection web page that it uses may include JavaScript that the client application can manipulateto retrieve the access and refresh tokens.

    Alternatively, a client application (native or web) may use the page https://login.instance_name/services/oauth2/success as their callback URL. Instead of actually loading the page on redirect, they should intercept the redirection URI and extract the parameters values. The refresh_token parameter values are only provided if the redirection URI is this URI or if the redirection URI uses a custom protocol.

    Once the client application has retrieved the access and refresh tokens, it can use them to make requests to Connect REST API.