Authentication
The Snapchat Marketing API uses access tokens to control access and authenticate requests, the access token will reflect the user permissions when used in API requests.
The access token should be included in all API requests to the server in the Authorization header in the following way:
Authorization: Bearer meowmeowmeow
Obtain App Credentials
OAuth apps are set up in the 'Business Details' section in Snap Business Manager, you need to be an Organization Admin to see the app dashboard, when setting up an app you need to agree to the Snap Developer Terms and the Snap Business Tools Terms.
Refer to this guide to setup your OAuth app in Business Manager.
When setting up an OAuth app you need to provide a name and a redirect_uri, the redirect_uri is where the user is redirected upon authentication.
Depending on your objectives you may want the redirect_uri to simply display the code value so that you can copy it and use it in an app built elsewhere to generate tokens, or you may choose to build the entry point for your entire app on the redirect_uri so that it may read the code value automatically upon user authentication.
Upon creation of an app you will be presented with client_id and client_secret, the secret is only ever displayed at the point of creation so you will need to keep track of this.
User Auth via Redirect
Direct the user's browser to the Authorization URL. The user will be presented with a login screen and confirmation prompt asking the user to authorize the OAuth App to act on behalf of the user.
GET https://accounts.snapchat.com/login/oauth2/authorize
Parameters
| Parameter | Default | Description |
|---|---|---|
| client_id | Client ID | |
| redirect_uri | URLEncoded Redirect URI (must match URI on OAuth App) | |
| response_type | Must be "code" | |
| scope | Refer to the scopes reference table below | |
| state | Optional; Will be passed through in redirect; Used for verification of request authenticity |
Scopes
| Scope | Description |
|---|---|
| snapchat-marketing-api | This scope allows the app to read and write to the Snapchat marketing APIs |
| snapchat-offline-conversions-api | This scope allows the app to read and write to the Snapchat Conversions APIs |
| snapchat-profile-api | This scope allows the app to read the Snapchat Public Profile APIs |
Note: To use multiple scopes please pass in a space separated list of scopes example scope=snapchat-marketing-api snapchat-offline-conversions-api
# Sample URL to redirect the OAuth users to - Single Scope
https://accounts.snapchat.com/login/oauth2/authorize
?client_id=4cxxxx8-1c33-xxxx-8798-xxxxxxxx
&redirect_uri=https://test.animalfarm.com/callback
&response_type=code
&scope=snapchat-marketing-api
# Sample URL to redirect the OAuth users to - Multiple Scopes
https://accounts.snapchat.com/login/oauth2/authorize
?client_id=4cxxxx8-1c33-xxxx-8798-xxxxxxxx
&redirect_uri=https://test.animalfarm.com/callback
&response_type=code
&scope=snapchat-marketing-api snapchat-offline-conversions-api
Receive the Redirected User
After the user approves or cancels the authorization, they will be redirected to your Redirect URI. If the user approved the request for the OAuth App to act on their behalf, there will be 2 query parameters passed along to your Redirect URI.
Parameters
| Parameter | Default | Description |
|---|---|---|
| code | One-time use code that can be exchanged for an Access Token and a Refresh Token | |
| state | Optional; Used for verification of request authenticity |
Generate an Access Token
In order to access the API on behalf of the user that just authorised the app you must generate an Access Token that represents the user. To generate an Access Token you must first receive a Code from a successful user OAuth Web Redirect Flow described above. Once you have the Code you can exchange it for a short-lived Access Token and long-lived Refresh Token. The Access Token is valid for 3600 seconds = 60 minutes.
# With shell, you can just pass the correct header with each request
curl -X POST \
-d "grant_type=authorization_code" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "code={code}" \
-d "redirect_uri={redirect_uri}"
https://accounts.snapchat.com/login/oauth2/access_token
The above command returns JSON structured like this:
{
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "32eb12f037712a6b60404d6d9c170ee9ae4d5b9936c73dd03c23fffff1213cb3",
"access_token": "0.MGQCxyz123"
}
HTTP Request
POST https://accounts.snapchat.com/login/oauth2/access_token
Parameters
| Parameter | Default | Description |
|---|---|---|
| client_id | Client ID | |
| client_secret | Client Secret | |
| code | One-time Use Code from User Redirect or Refresh Token | |
| grant_type | "authorization_code" | |
| redirect_uri | URLEncoded Redirect URI. Required when grant_type=authorization_code. Must match redirect_uri from the previous /authorize call |
Refresh the Access Token
Access Tokens are short-lived. When you receive a 401 token expired error, you should use your Refresh Token to generate a new Access Token and retry the request. Many standard OAuth2 libraries can handle this expiration-retry pattern for you.
# With shell, you can just pass the correct header with each request
curl -X POST \
-d "refresh_token={refresh_token}" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "grant_type=refresh_token" \
https://accounts.snapchat.com/login/oauth2/access_token
The above command returns JSON structured like this:
{
"access_token": "0.MGQCxyz123",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "32eb12f037712a6b60404d6d9c170ee9ae4d5b9936c73dd03c23fffff1213cb3",
"scope": "snapchat-marketing-api"
}
HTTP Request
POST https://accounts.snapchat.com/login/oauth2/access_token
Parameters
| Parameter | Default | Description |
|---|---|---|
| client_id | Client ID | |
| client_secret | Client Secret | |
| grant_type | "refresh_token" | |
| refresh_token | The refresh token you received when generating your first access token |
Full Web Flow Example
1. Open the authorize link in a browser:
https://accounts.snapchat.com/login/oauth2/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope=snapchat-marketing-api&state=wmKkg0TWgppW8PTBZ20sldUmF7hwvU
2. Login & Authorize via UI
3. Locate "code" query parameter in the redirect
4. Exchange code for access token + refresh token
curl -X POST \
-d "code={one_time_use_code}" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "grant_type=authorization_code" \
-d "redirect_uri=redirect_uri"
https://accounts.snapchat.com/login/oauth2/access_token
5. When the access token expires, generate a new one using the refresh token
curl -X POST \
-d "refresh_token={refresh_token}" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "grant_type=refresh_token" \
https://accounts.snapchat.com/login/oauth2/access_token
The above command returns JSON structured like this:
{
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "xyz",
"access_token": "0.1234567890"
}
Access Token Expiration
Access Tokens are short-lived and expire after a number of seconds indicated by the expires_in property in the response, currently the expiry is 3600 seconds = 60 minutes.
When a request is attempted with an expired token, the response will be a 401 Not Authorized with additional headers.
< HTTP/1.1 401 Unauthorized
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers: Content-Type, Authorization
< WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired"
< X-Cloud-Trace-Context: e0fdbe35c49ad238e624635b6a45813d;o=1
< Date: Mon, 15 Aug 2016 21:10:01 GMT
< Content-Type: text/html
< Server: Google Frontend
< Content-Length: 0