API Authentication

Creating an API key

To use the Narrativ API, you will need to create an API key for your user account. Navigate to the Developer Options page and follow the directions there.

Using your API key

Unless otherwise indicated, Narrativ API requests must include a valid API key. Send your API key in the HTTP Authorization header, prefixed with the scheme NRTV-API-KEY. For example:

curl -i -H 'Authorization: NRTV-API-KEY Sy8xLzE2MTE3MDIxNzY3NDM0OTc0MDcv' \
    https://api.narrativ.com/api/v1/tokeninfo/
HTTP/1.1 200 OK

{
  "info": {
    "error": false,
    "status": 200
  },
  "data": [
    {
      "token_id": 1001,
      "uid": 2,
      "description": "My API Key",
      "datetime_created": "2017-07-25T20:58:38Z",
      "datetime_updated": "2017-07-25T20:58:38Z",
      "datetime_active": "2017-07-25T20:58:38Z",
      "datetime_expires": null,
      "datetime_last_used": null,
      "is_enabled_by_user": true
    }
  ]
}

If a valid API key is not sent, the server will return an HTTP 401 error:

curl -i -H 'Authorization: NRTV-API-KEY TestInvalidAPIKey' \
    https://api.narrativ.com/api/v1/tokeninfo/
HTTP/1.1 401 UNAUTHORIZED

{
  "info": {
    "error": true,
    "status": 401
  },
  "data": [],
  "error": {
    "code": 4302,
    "message": "Invalid API token",
    "data": null
  }
}

Keeping your account secure

Remember to keep your API key secret, since anyone who has it can use it to access your Narrativ account. If you ever lose your API key, you can visit the Developer Options page to disable it and create a new one.