API documentation


You authenticate to the API by providing your Connector ID and Secret in the request. You can find it in any connector settings pane.

Additionally you can authenticate “As a User” or “As an Account” by passing a JSON web token in Hull-Access-Token - This is the way you can submit Events and Attributes on a given user. Checkout Identity Resolution for information on how to generate this JWT

  • When you authenticate as a user from the Client-side within Hull.js, the library passes this JWT token in every call. You have limited access to the API, and can only perform tracking calls, traits, and call the Alias method.

Authenticated requests

curl -X DELETE http://ORGANIZATION_NAMESPACE.hullapp.io/api/v1/:id \
     -H "Hull-App-Id: CONNECTOR_ID" \
     -H "Hull-Access-Token: JWT_OR_CONNECTOR_SECRET" \

From a server, set up Hull-App-Id and Hull-Access-Token HTTP headers to provide the Connector Id and Access Token.

The Hull-Access-Token is either the Connector Secret you can find in your Connector’s Settings, or a User or Account-scoped JSON Web token generated by the library.

The Hull Node library handles all of this for you


You can also send your App ID and the Access Token as parameters, although we STRONGLY discourage it.

Beware to never expose your CONNECTOR_SECRET on the client side, only use these authenticated methods from your own server !

Authentication for sending data to the Firehose

When sending data to the firehose, authentication happens in each header object in the array that you will send.

You need to create and pass a JWT in headers["Hull-Access-Token"] for each entry in the batch array. This JWT will include the claims for the command you send.

  "batch": [
    { "headers": { "Hull-Access-Token": "JWT_WITH_CLAIMS_1" }, "body": { PAYLOAD_1 } },
    { "headers": { "Hull-Access-Token": "JWT_WITH_CLAIMS_2" }, "body": { PAYLOAD_2 } },