Njord Analytics API

Summary

Njord Analytics is based on an API that powers every feature of the web app. It is possible to access this API for the purpose of automating tasks.

All API requests and responses are based on the GraphQL format specification. It is recommended to familiarize yourself with the query language and conventions of GraphQL to use the Njord Analytics API effectively.

You can access an interactive GraphQL API console at https://app.sailnjord.com/admin/graphql which allows you to:

Send GraphQL requests (queries and mutations) to the live API without any programming required
Browse the API documentation outlining all available queries and mutations and their input and output types (see "Documentation Explorer" symbol in the sidebar)

Note: All requests entered in this console are executed under your currently logged in user account, with all associated privileges and the ability to delete data if not careful (most mutations that delete data are clearly named "delete..." however). To avoid damage, send a simple query like { currentUser { name } } to confirm under which user name you are logged in, and consider using a test account without access to your real data if you want to be on the safe side.

The GraphQL API endpoint to send HTTP requests to when not using the console is https://api.prod.sailnjord.com/graphql

Authentication

Virtually all GraphQL queries and mutations require authorization in the form of an Authorization HTTP header sent with each HTTP request to the GraphQL API endpoint.

API Key

For many automated tasks that are tied to one specific user account, an API key is a suitable form of access control. Create one from your Njord account page at auth.sailnjord.com under API keys: give it a name, choose which permissions it should have per area (boats · events, races & trainings · sailing data · fleet tracking · account — read access is pre-selected, write and delete are off by default), and pick an expiry. The key value (starting with njord_prod_) is shown once at creation — copy it then; it cannot be retrieved later.

Send the key as a bearer token with each GraphQL API request:

Authorization: Bearer njord_prod_...

Keys can be revoked from the same page at any time and stop working within a minute. A key only ever has the access you gave it: the permissions you selected, bounded by your own account's boat access at the time of each request. Grant only the permissions your use case needs — every query and mutation in the schema documents its required permission, and your effective permissions are visible via { principals { permissions } }.

Older self-generated keys (from the currentUser.apiKey query in the console) keep working for now, but that mechanism is deprecated — new integrations should use portal-created keys, which can be revoked and report when they were last used.

OAuth

For advanced use cases where different users require access to the Njord API, integration with Njord's OAuth identity provider is possible. Please contact us if you're interested.

Use Cases

To learn about useful queries and mutations, it can be helpful to inspect the API queries that the Njord Analytics web app performs - simply use the web development tools of your browser of choice, perform the desired task and inspect network requests and responses to the GraphQL API endpoint.