Using the Highnote API

The URL used for the Highnote API depends on your environment. The endpoint will be /graphql, but the sub-domain will differ.

Highnote API requests are authenticated using Basic auth where your API Key is provided as the username. A password is not required. See below for details on obtaining API keys.

To make a request, pass an Authorization header with your base64 encoded API key.

Requests sent with missing or invalid credentials will receive a 401 Unauthorized response code.

Obtaining an API Key

You can obtain an API key via the Highnote Dashboard by navigating to API Keys in Developers, and creating a new key. If you don't yet have a Highnote account, you can sign up for one.

The newly generated key will only be presented once and cannot be retrieved later. API keys can be revoked at any time via the Highnote Dashboard.

The Highnote API requires Authorization and Content-Type headers. Since the API accepts and returns JSON, pass a Content-Type header with the value of application/json.

The following HTTP status codes will be returned from the API.

Read more about GraphQL responses and formats in the spec.

The Highnote API returns JSON response bodies. The responses will contain the following:

More about troubleshooting with Request IDs in the Highnote API.

The Highnote GraphQL API accepts POST requests with JSON payloads. The requests must contain a string named query but can also contain variables and operationName.

query

The query is the GraphQL operation (query, mutation, etc.) that you are calling.

Copy code snippet
{
  "query": "{ ping }"
}

You can make multiple GraphQL "requests" in a single call. In this case, you would still provide a single query value with all calls as a string.

Copy code snippet
{
  "query": "query Ping {\n  ping\n  ping2: ping\n}"
}

variables

The variables field is used to pass dynamic input to queries and mutations.

Here is an example of passing variables to the IssuePaymentCard mutation.

Copy code snippet
mutation IssuePaymentCard($input: IssuePaymentCardInput!) {
  issuePaymentCard(input: $input) {
    ... on PaymentCard {
      id
    }
  }
}

For this mutation, the payload would be created like this:

Copy code snippet
const payload = JSON.stringify({
  query: `
mutation IssuePaymentCard($input: IssuePaymentCardInput!) {
  issuePaymentCard(input: $input) {
    ... on PaymentCard {
      id
    }
  }
}
`,
  variables: {
    input: {
      cardholderId: "cardholder_id",
      cardProductId: "card_product_id",
      options: {
        activateOnCreate: true,
        expirationDate: "2022-01-01T23:59:59Z",
      },
    },
  },
});

Learn more about using variables in GraphQL.

operationName

In the case that you have a GraphQL document that contains multiple operations, you can use operationName to tell the server which to execute. For example, given the following GraphQL with both IssuePaymentCard and Ping, to run Ping, you would provide HelloWorld as the operationName on your payload:

GraphQL document:

Copy code snippet
query HelloWorld {
  ping
}

mutation IssuePaymentCard($input: IssuePaymentCardInput!) {
  issuePaymentCard(input: $input) {
    ... on PaymentCard {
      id
    }
  }
}

Payload:

Copy code snippet
{
  "query": "...",
  "operationName": "HelloWorld"
}

Read more about using operationName here.