Connect REST API Developer Guide

Connect REST API Developer Guide
Introduction
When to Use Connect REST API
Connect REST API Architecture
Connect REST API 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
Perform Cross-Origin Requests 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

OAuth and Connect REST API

Connect REST API uses OAuth to securely identify your application before connecting to Salesforce.

OAuth is an open protocol that allows secure authentication for access to a user's data, without handing out the user's username and password. It is often described as the valet key of software access: a valet key only allows access to certain features of your car: for example, you can’t open the trunk or glove compartment using a valet key.

When you use OAuth, you can avoid storing login credentials in your application. Instead, your application can prompt the user to log in using a standard Salesforce page, which returns an access token to your application. Your application can use this access token to access Connect REST API web services. This approach to authentication can be used in both mobile apps and from a web page.

Connect REST API uses OAuth 2.0.

Connected Apps

To use Connect REST API, you must create a REST entry point in your organization. Salesforce defines this entry point as a connected app definition.

For an example of creating a connected app definition, see Step Two: Set Up Authorization.

Considerations when creating and using a connected app:
  • The following maps the labels used in the connected app definition to OAuth terms:
    Connected App Label OAuth Term Description
    Consumer Key client_id A unique identifier that identifies your application to Salesforce.
    Consumer Secret client_secret A secret key associated with your application.
    Callback URL redirect_uri A URL associated with your client application. In some contexts, the URL must be a real URL that the client’s web browser is redirected to. In others, the URL isn’t used; however, between your client application and the server (the connected app definition) the value must be the same. We suggest using a value that identifies the application, such as http://mycomponent.myapp.
  • If you are developing a mobile app, you can use the following value for the Callback URL (redirect_uri) to avoid setting up an application server of your own. 
    1https://login.instance_name/services/oauth2/success
    Don’t use this value when developing a web application.
  • Your connected app doesn’t have to reside in the same org as your users. The connected app you create can be used to sign in to any org.
  • We recommend creating more than one connected app definition: one for testing and one for production. If you create only one, you must change the value of the Callback URL to reflect the location of your application code. In addition, we suggest creating more than one connected app if you are developing for different platforms, such as iOS and Android.

OAuth Basics

  • OAuth grants access by client applications to resources owned by resource owners. In terms of OAuth, a resource is anything that must be kept secured. For Connect REST API, the resource we are concerned about protecting is all the data accessible through the API.
  • It’s up to a resource owner to grant access to resources. In our context, the resource owner is a combination of the administrator (who administers users and the connected app) and the users (who log in and grant access to third-party applications).
  • When an application wants to access a resource, it requests authorization from the resource owner. OAuth outlines various ways that an application can be granted access to a resource. These ways are referred to as grant types or flows. Different flows are suitable for different contexts.
  • Once a client application has been authorized to access to a resource, the client application is given an access token and a refresh token. The authorized client application must include the access token in any subsequent web service requests to identify itself. Access tokens have a limited lifetime. When an access token expires, the authorized client application can make a special request using the refresh token to obtain a new access token.

OAuth Flows

A user must be authenticated before accessing Salesforce. OAuth has multiple authentication flows. There are several steps in each authentication flow, as dictated by the OAuth standard and the type of application trying to access Salesforce. On successful authorization, the client application is provided with access and refresh tokens.

Salesforce supports these flows for use with the Connect REST API.

In addition, you can use the refresh token to get a new access token after your application has been authorized for access.

For detailed information about using OAuth with digital experiences, see Salesforce Help.

Revoke Access

After users have been granted access to a client application, they can revoke access by clicking Revoke in the Connected Apps section of their Personal Information page.

More Resources

Connect REST API shares some infrastructure with the REST API. The information on authentication in these tutorials is also applicable to Connect REST API.
The authentication part of the REST API is shared with Connect REST API. We suggest this library that supports the REST API.
OAuth is a popular authentication standard. Client libraries for OAuth help smooth the development process for client applications. We suggest these client programming libraries.