Authentication

Marketo’s REST APIs are authenticated with 2-legged OAuth 2.0.  Client IDs and Client Secrets are provided by custom services that you define.  Each custom service is owned by an API-Only user which has a set of roles and permissions which authorize the service to perform specific actions.  An access token is associated with a single custom service.  Access token expiration is independent of tokens associated with other custom services that may be present in an instance.

Creating an Access Token

The Client ID and Client Secret are found in the Admin > LaunchPoint menu by selecting the custom service, and clicking View Details.

doc-rest-api-authentication-service-view-details

doc-rest-api-admin-launchpoint-credentials

The Identity URL is found in the Admin > Web Services menu in the REST API section.

doc-rest-api-admin-web-services-identity-url

Create an access token using an HTTP GET request like so:

If your request was valid, you will receive a JSON response similar to the following:

Response Definition

  • access_token – The token that you pass with subsequent calls to authenticate with the target instance.
  • token_type – The OAuth authentication method.
  • expires_in – The remaining lifespan of the current token in seconds (after which it will be invalid).   When an access token is originally created, it’s lifespan is 3600 seconds or 1 hour.
  • scope – The owning user of the custom service that was used to authenticate.

Using an Access Token

When making calls to REST API methods, an access token must be included in every call in order for the call to be successful.

There are two methods that you can use to include a token in your calls, as an HTTP header, or as a query string parameter:

1. HTTP Header

Authorization: Bearer cdf01657-110d-4155-99a7-f986b2ff13a0:int

2. Query Parameter

access_token=cdf01657-110d-4155-99a7-f986b2ff13a0:int

Tips and Best Practices

Managing access token expiration is important to ensure that your integration works smoothly and prevents unexpected authentication errors from occuring during normal operation.  When designing authentication for your integration, be sure to store the token and expiration period contained in the Identity response.

Prior to making any REST call, you should check the validity of the token based on its remaining lifespan.  If the token is expired, then renew it by calling Identity endpoint.  This will help ensure that your REST call never fails due to an expired token.  This helps you manage the latency of your REST calls in a predictable fashion, which is crucial for end-user-facing applications.

If an expired token is used to authenticate a REST call, the REST call will fail and return a 602 error code.  If an invalid token is used to authenticate a REST call, a 601 error code will be returned.  If either of these codes are received, the client should renew the token by calling Identity endpoint.

If you call the Identity endpoint before your token has expired, the same token and the remaining lifespan will be returned in the response.

Remember that your access tokens are owned on a per-Custom-Service basis and not on a user basis.  Even though two Identity responses may be scoped to the same user, the access tokens and expiration periods will be independent of each other if they were made with credentials from two different services.  Keep this in mind when you have multiple sets of credentials in the same application; the Client Id can be a useful key for managing them independently.