Authentication

You authenticate to the API by providing your Ship ID and Secret in the request. You can find it in your admin.

Additionnally you can authenticate “As a User” by passing a JWT token in Hull-Access-Token - This is the way you can submit Events and Attributes on a given user.

  • 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 access your own profile.
  • When you authenticate as an admin (with a Ship ID & Secret) Server-side, in Ships, you have full access to the API

Authenticated requests

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

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

The Hull-Access-Token is either the App Secret you can find in your Ship’s Advanced Settings, or a User-scoped token generated by the library.

The Hull JS Node library handles all of this for you.

curl -X DELETE http://ORGANIZATION_NAMESPACE.hullapp.io/api/v1/:id?app_id=SHIP_ID&access_token=JWT_OR_SHIP_SECRET

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

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

Making requests on behalf of a user

curl -X PUT http://NAMESPACE.hullapp.io/api/v1/:id/traits \
     -H "Hull-App-Id: SHIP_ID" \
     -H "Hull-Access-Token: JWT_OR_SHIP_SECRET" \
     -H "Hull-User-Id: USER_ID"

When you do server-to-server calls, you will frequently want to perform calls as one of the end-users. To do that, provide the user id in the Hull-User-Id header.

The easiest way to do this from the server-side is to use our Hull Node library