Authentication

Every request needs a token, passed as a bearer token in the Authorization header. Schema introspection is the only exception.

Authorization: Bearer <YOUR_API_KEY>

The token sets the context the request runs in, and so what it can reach.

Channel context

Integrators authenticate as a channel: a merchant's store connected to Submarine. The channel's API key gives access to that store's data.

To find the API key:

1. Open the Submarine app in the store's Shopify admin.
2. Go to Settings.
3. Under API access, find the GraphQL API card and show the API key.

Each store has its own API key. Keep it secret, because anyone who holds it has API access to the store's Submarine data.

Customer context

Storefronts and customer accounts call the API as a single customer. In this context a request can only reach that customer's own subscriptions, campaign orders and payment records, plus the products and subscription plans on offer. The customer can manage their own subscriptions and campaign orders and update their own details.

Submarine's storefront and customer account integrations issue customer tokens automatically, so integrators don't need to create or store them. Customer tokens expire after a few minutes.

Unauthenticated requests

The API rejects a request without a valid token before it reaches any Submarine service. The response has no data, only an error explaining what was wrong with the token:

{
  "errors": [
    { "message": "missing or invalid Authorization header" }
  ]
}