Skip to main content

Authenticate to analytics

Trade your Paylode API key for a short-lived analytics token, then use that token to query your metrics.

Analytics uses a two-step handshake. Your API key never goes to the query host directly. Instead you call Paylode's analytics endpoint once to mint a short-lived token, and that token is what authorizes your queries. The token is scoped to your account, so every query you run with it already sees only your own data.

How it works​

  • recap.paylode.com issues tokens. You authenticate here with your X-API-Key header and get back a signed token.
  • cube.paylode.com answers queries. You send the minted token here to run a query.

Tokens are short-lived — valid for about 5 minutes — so mint one when you start a batch of queries and refresh it before it expires. The mint response tells you exactly when the token expires, so you don't have to guess.

Before you begin​

  • Your Paylode API key. It's the same key you use for every other API call. See Authentication for where to find it and how the X-API-Key header works.

Steps​

1. Mint a token​

Call the token endpoint with your API key. There's no request body.

curl https://recap.paylode.com/cube/token \
  -H "X-API-Key: sk_example_a1b2c3d4e5f6"
const res = await fetch("https://recap.paylode.com/cube/token", {
  headers: { "X-API-Key": "sk_example_a1b2c3d4e5f6" },
});
const { token, expiration } = await res.json();

A 200 returns the token and its expiry (response trimmed):

{
  "token": "eyJhbGciOiJIUzI1NiJ9.EXAMPLE_PAYLOAD.EXAMPLE_SIGNATURE",
  "expiration": 1748785620000,
  "serverTime": {
    "timestamp": "2026-06-01T13:42:00Z",
    "epoch_timestamp": 1748785320
  }
}

expiration is the token's expiry as epoch milliseconds. serverTime is the server's clock when the token was minted — compare the two to know how long you have before you need a fresh token.

2. Query with the token​

Send the token to the query host in the Authorization header.

curl https://cube.paylode.com/cubejs-api/v1/meta \
  -H "Authorization: eyJhbGciOiJIUzI1NiJ9.EXAMPLE_PAYLOAD.EXAMPLE_SIGNATURE"
caution

Pass the token as-is — do not add a Bearer prefix. The analytics query host expects the raw token value in the Authorization header. A Bearer prefix will fail authentication.

Once the token is accepted, you can run queries. See Query your metrics for the query format and a worked example.

Troubleshooting​

  • 401 from the token endpoint. Your X-API-Key is missing or not recognized. Confirm you're sending the same key that works for your other API calls — see Authentication.
  • 403 from the token endpoint. You passed a clientId query parameter. That parameter is reserved for Paylode administrators; as a client, omit it — your token is scoped to your own account automatically.
  • Queries start failing after a few minutes. Your token has expired. Mint a new one and retry. Tokens are short-lived by design; refresh before expiration.

For the exact request and response schema of the token endpoint (operation issueCubeToken), see the API Reference.