API Access & Overview

The Chartboost API utilizes Restful API endpoints, providing developers programmatic access to manage their Chartboost resources for Monetization. Using this API you can get, create, update, or delete your app(s), ad location, and list management resources without having to access the Chartboost platform user interface.

To get started, review and accept the Chartboost App Disclosures on the User Access Management page in the Chartboost platform. Then review the access and authentication process detailed below before moving on to the specific APIs.

• App Management API
• Ad Locations API
• Analytics API
• List Management API

For Chartboost SDK developers, the following API references are available:

• iOS SDK API Reference

API access URL endpoint 🔗

Obtaining your API client credentials 🔗

The Chartboost API uses the OAuth2 standard protocol for “Client Credentials Grant” (RFC ft-ietf-oauth-v2: The OAuth 2.0 Authorization Framework) to grant authorization.

A client must pass a client_id and client_secret value to obtain an access token for authentication.

To find your client ID and client secret:

1. Log in to your Chartboost platform.
2. Click on your user icon at the top right corner.
3. Select Company info & settings.
4. Select Access Management from the left navigation column.
5. Click on Refresh API v5 Credentials to obtain new client ID and client secret credentials.
   • For v4 users, click on Refresh API v4 Credentials to obtain your client ID and client secret credentials.
   • The client secret key is only displayed when you refresh the credentials. You will not be able to see it again once you refresh or leave this page. If you loose your client secret key, you will have to re-authenticate with a new client ID and secret credentials.

Authentication 🔗

An access token is required to access and make requests to the Chartboost public API server. Obtain your access token by passing in your client id and client secret credentials to the authentication server.

Version 5 authentication 🔗

Endpoint POST /oauth/token
URL https://chartboost.us.auth0.com/oauth/token

Send a request to the OAuth2 token endpoint using your client ID and client secret credentials in the request body. (Client Credentials Flow: Request tokens)

POST /oauth/token HTTP/1.1
Host: chartboost.us.auth0.com
Content-Type: application/json

{
  "client_id": YOUR_CLIENT_ID,
  "client_secret": YOUR_CLIENT_SECRET,
  "audience": "https://public.api.gateway.chartboost.com",
  "grant_type": "client_credentials"
}

The Auth0 authorization server will validate and respond with an access token and expiration time in seconds; effective immediate. You must acquire a new access token after expiration, but you can use the same client credentials.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"Bearer",
  "expires_in":86400
}

Version 4 authentication 🔗

Endpoint POST /v4/token
URL https://api.chartboost.com/v4/token

Send a request to the token endpoint (RFC 6749 - Section 4.4.2. Access Token Request) with your client ID and client secret credentials in the request body (RFC 6749 - Section 2.3.1. Client Password). Encode them using the HTTP Basic authentication scheme base64(client_id:client_secret).

POST /v4/token HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

The server will then respond with an access token and expiration time in seconds; effective immediate (RFC 6749 - Section 4.4.3. Access Token Response). You must acquire a new access token after expiration, but you can use the same client credentials.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"Bearer",
  "expires_in":3600
}

Using the public API 🔗

After authenticating against the Public API, every subsequent call must use the obtained Access Token to grant access to the protected resources. To do so, the client must use the Authorization Header with the “Bearer” token (as described in RFC ft-ietf-oauth-v2-bearer: The OAuth 2.0 Authorization Framework: Bearer Token Usage). Client call example:

Version 5 header example

GET /v5/apps HTTP/1.1
Host: api.chartboost.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Version 4 header example

GET /v4/apps HTTP/1.1
Host: api.chartboost.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Troubleshooting authentication errors 🔗

Any issue with the authentication will produce an error from the list below (as described in RFC 6749 - Section 5.2. Error Response):

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error":"invalid_request"
}