API Access & Authentication

Getting Started 🔗

The Chartboost Publisher API (V4) is the latest version of 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 and Ad-Location resources without having to access the dashboard user interface.

To get started, make sure you read this page first before moving on to the specific APIs.

API URL Endpoint 🔗

The latest Chartboost API endpoint is: https://api.chartboost.com/v4
All examples in this documentation assume that you are using the latest API endpoint as the root URL.

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.

Using the Client Credentials Flow, a client may obtain an Access Token after passing its client_id and client_secret values to the authorization server.

First, you need to obtain (or generate) a new client_id and client_secret for your service account. To do that, log in to the Chartboost platform and navigate to the User Access Management page.

On that page, you will find your client_id and client_secret values. If you do not see the client_secret field, click on “Refresh Credentials” to generate new ones. Make sure to copy the client_secret before navigating away from that page since it will be hidden the next time you refresh that page.

Authentication 🔗

POST /v4/token 🔗

After obtaining the client_id and client_secret from the step above, the client should get an Access Token by sending a request (as described in RFC 6749 - Section 4.4.2. Access Token Request) to the token endpoint, using its client credentials (client ID and client secret, as described in RFC 6749 - Section 2.3.1. Client Password) and encoding them using the HTTP Basic authentication scheme (base64(client_id:client_secret)), like in this example:

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

grant_type=client_credentials

And the server will provide an Access Token (as described in RFC 6749 - Section 4.4.3. Access Token Response), with a relative expiration, like in this example:

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
}

Every subsequent request to the API will require a valid access token to be passed in the Authorization header as described in the next section Using the public API.

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:

GET /v4/apps HTTP/1.1
Host: server.example.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):

Parameter Response
error REQUIRED. A single ASCII [USASCII] error code. Values for the “error” parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
error_description OPTIONAL. Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the “error_description” parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
error_uri OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the “error_uri” parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E.
invalid_request The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
invalid_client Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the “Authorization” request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the “WWW-Authenticate” response header field matching the authentication scheme used by the client.
invalid_grant The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
unauthorized_client The authenticated client is not authorized to use this authorization grant type.
unsupported_grant_type The authorization grant type is not supported by the authorization server.
invalid_scope The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error":"invalid_request"
}

Last modified November 27, 2023