1. When using OAuth 2.0, be sure to keep the OAuth secret safe.
  2. Avoid using Basic HTTP authentication scheme, when possible.

CSRF protection

By default, each API session is protected with the CSRF token.

You can read more about CSRF here.

Use protected sessions

Unless the CSRF protection is explicitly disabled during authentication, the successful authentication response will contain the session token in the X-CSRF-Token response header (in addition to the session ID in the response body):

HTTP/1.1 200 OK
Content-Type: application/json
X-CSRF-Token: DBYmfYEjHNzXI1tvnUAbu8xxD9gWH6bnTVTuqj2RAc1w2fuwuOTCK01yFLO3bksYfXAdCzABauGfZChfivS2BHIc0a5r
X-API-Version: 1

    "status": 200,
    "session_id": "lNlZU4goODSinE8DkW3PKs79d60c497f0a5c507e897da818682d6cf21321fca5la58k2s8ZxGYYRfjcuAVgRFA"

The API client must save this token in a secure storage.

Protect API requests

If the session is protected with the CSRF token, this token should be supplied with every API request. This can be done via the X-CSRF-Token request header, as follows:

POST /api/v1/tests.json HTTP/1.1
X-CSRF-Token: DBYmfYEjHNzXI1tvnUAbu8xxD9gWH6bnTVTuqj2RAc1w2fuwuOTCK01yFLO3bksYfXAdCzABauGfZChfivS2BHIc0a5r

The CSRF token is required for unsafe HTTP methods POST, PUT and DELETE. So, if it's not supplied, the API service will return the CSRF_FAILED error.

Disable CSRF protection

The CSRF protection can be disabled for new sessions by adding the X-CSRF header in the authentication request (that creates the session), as follows:

X-CSRF: false


Use CORS instead of JSONP to access the API service from JavaScript, when possible.