Authentication

POST /v2/oauth/token

Returns an access token. The access token must be included in all other requests as a Bearer token. Before you begin, ensure you have a client ID and secret from Instacart. You need to pass these values in the request.

Request

When you make the request, specify the following values for Carrot Ads:

• grant_type - The grant type must be client_credentials.
• scope - Leave empty for all scopes, or set to connect:ian for ads only.

The Carrot Ads API uses the same authentication endpoint that you use with all Connect APIs. For more information about authentication, see Authentication.

The generated request examples use connect.instacart.com. For Carrot Ads, mint the token on the OAuth host Instacart assigned for your integration, then send ads requests to your ads data host. Token host and ads data host vary by integration. For staging, a production token is valid against the staging data host.

For host pairing, test_only, and staging behavior, see Environments and testing.

Field	Type	Required	Description
client_id	string		The client ID.
client_secret	string		The client secret.
grant_type	string		The grant type.
scope	string		The APIs that this token can access. Default is all the APIs specified in the retailer application configuration.
code	string		The authorization code.
redirect_uri	string		The redirect URI when the authorization code was generated.
assertion	string		The assertion.

Request examples

cURL

curl --request POST \
  --url https://connect.instacart.com/v2/oauth/token \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "client_id": "string",
  "client_secret": "string",
  "grant_type": "string",
  "scope": "string",
  "code": "string",
  "redirect_uri": "string",
  "assertion": "string"
}'

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/oauth/token")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .body("{\n  \"client_id\": \"string\",\n  \"client_secret\": \"string\",\n  \"grant_type\": \"string\",\n  \"scope\": \"string\",\n  \"code\": \"string\",\n  \"redirect_uri\": \"string\",\n  \"assertion\": \"string\"\n}")
  .asString();

Python

import http.client

conn = http.client.HTTPSConnection("connect.instacart.com")

payload = "{\n  \"client_id\": \"string\",\n  \"client_secret\": \"string\",\n  \"grant_type\": \"string\",\n  \"scope\": \"string\",\n  \"code\": \"string\",\n  \"redirect_uri\": \"string\",\n  \"assertion\": \"string\"\n}"

headers = {
    'Accept': "application/json",
    'Content-Type': "application/json"
}

conn.request("POST", "/v2/oauth/token", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Go

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.instacart.com/v2/oauth/token"

	payload := strings.NewReader("{\n  \"client_id\": \"string\",\n  \"client_secret\": \"string\",\n  \"grant_type\": \"string\",\n  \"scope\": \"string\",\n  \"code\": \"string\",\n  \"redirect_uri\": \"string\",\n  \"assertion\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

Field	Type	Required	Description
access_token	string		The token to be used to authenticate requests.
token_type	string		The token type.
expires_in	number		The number of seconds the token will expire in.
created_at	number		The epoch time of when the token was created.
scope	string		The scope of the token.

Response examples

The following response example is a generic Connect example. For Carrot Ads, the scope returned is connect:ian.

200 Success

200 Access token generated

{
  "access_token": "mhtEdMZYPypuW_I0fYken8cAqE7llDaoNefHSeVj9u4",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "connect:fulfillment",
  "created_at": 1603897760
}

Authentication Errors

HTTP Code	Cause	Error	Description
400	Invalid authorization code or redirect URI	"invalid_grant"	"Assertion is not provided or invalid assertion provided for the grant_type."
401	Invalid client ID or secret	"invalid_client"	"Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method."
403	Query Params Forbidden	"query_params_forbidden"	"Providing OAuth credentials as query parameters may cause them to be compromised. Please ensure the credentials are rotated."