Get an access token

Learn how to get a token that lets you access endpoints in the Segments API.

Prerequisites

• Your OAuth application's credentials.
• The base URL of your assigned Connect development or production server.

Generate an access token

To generate an access token, send a POST request to /v2/oauth/token. In the request body, provide your OAuth application's client_id and client_secret and set grant_type to client_credentials. Although optional, it's recommended that you also provide scope. For more information, see Defining scope.

curl --request POST \
 --url 'https://<instacart_development_domain>/v2/oauth/token' \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --data '{
    "client_id": "<your_client_id>",
    "client_secret": "<your_client_secret>",
    "grant_type": "client_credentials",
    "scope": "<scope>"
}'

The response contains the generated access_token.

{
  "access_token": "<your_access_token>",
  "token_type": "Bearer",
  "expires_in": 86400,
  "created_at": 1603897760
}

Use the access token

Cache access_token and then pass it in the Authorization header of requests to Segments API endpoints that are within scope. The token is valid for 24 hours, after which it expires and you need to generate a new one.

Defining scope

You're not required to define scope, but if your request omits it, the returned token provides access to the full set of APIs that have a grant_type of client_credentials and are provisioned by your OAuth application. By defining scope, you can instead request a token that provides access to a subset of those APIs.

tip

Best practice is to limit scope to only the Segments API endpoints needed for your use case.

To provide multiple scope values in the same request, separate each by a whitespace. For example, connect:marketing:create_membership_segment connect:marketing:get_segment.

For each endpoint in the Segments API, the following table lists its scope:

Endpoint	Scope
Create a membership segment	connect:marketing:create_membership_segment
Get a segment	connect:marketing:get_segment
List segments	connect:marketing:list_segment
Add members to a segment	connect:marketing:add_to_membership_segment
Remove members from a segment	connect:marketing:remove_from_membership_segment
Clear a segment's membership	connect:marketing:clear_membership_segment
Get clear membership status	connect:marketing:get_clear_membership_segment_status