Authentication

The Chartmetric API uses a two-token model:

Token	Lifetime	Purpose
Refresh token	Long-lived	Identifies you as an API user. Exchanged for short-lived access tokens.
Access token	1 hour	Sent on every API request in the `Authorization` header.

1. Obtain a Refresh Token

Refresh tokens are issued per API user. To sign up, email hi@chartmetric.com. The token is delivered to your personal email.

Refresh tokens carry full account privileges:

Never commit them to source control.
Never embed them in client-side / browser code.
Store in a secrets manager or environment variable on the server side only.

If you suspect a refresh token is compromised, contact hi@chartmetric.com for a rotation.

2. Mint an Access Token

Exchange the refresh token at POST https://api.chartmetric.com/api/token.

Request:

curl -X POST https://api.chartmetric.com/api/token \
  -H "Content-Type: application/json" \
  -d '{"refreshtoken":"YOUR_REFRESH_TOKEN"}'

Body fields:

Field	Type	Required	Description
`refreshtoken`	string	yes	Your Chartmetric refresh token.

Response (200):

{
  "token": "eyJhbGciOi...",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "..."
}

Field	Type	Description
`token`	string	Access token. Use as `Authorization: Bearer <token>`.
`expires_in`	number	Seconds until the access token expires.
`refresh_token`	string	Refresh token to use for the next exchange.
`scope`	string	Granted access scope.

3. Call the API

Send the access token on every request:

curl https://api.chartmetric.com/api/artist/206557 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Reuse the same access token until it expires. Do not call /api/token per request — it counts against rate limits and adds latency.

4. Handle Expiry

Access tokens expire after 1 hour. When they do, requests return 401 Unauthorized. Re-mint by calling /api/token again with your refresh token.

A simple pattern: cache the access token plus an absolute expiry timestamp; refresh when the timestamp is within a small buffer (e.g., 60s) of now.

import time
from requests import post

HOST = 'https://api.chartmetric.com'
REFRESH_TOKEN = '...'

_token = None
_exp = 0

def access_token():
    global _token, _exp
    if _token and time.time() < _exp - 60:
        return _token
    res = post(f'{HOST}/api/token', json={'refreshtoken': REFRESH_TOKEN}).json()
    _token = res['token']
    _exp = time.time() + res['expires_in']
    return _token

5. Errors

Status	Meaning	Action
`400`	Malformed request body.	Verify JSON and the `refreshtoken` field name.
`401`	Invalid or expired token.	Re-mint an access token. If the refresh token itself is rejected, contact support.
`403`	Scope does not permit the resource.	Check your plan / scope.
`429`	Rate limit exceeded.	Back off using `X-RateLimit-Reset`. See Rate Limits & Plans.

Troubleshooting

Refresh token rejected: confirm no leading/trailing whitespace and that the token has not been rotated. Contact hi@chartmetric.com.
Access token works then suddenly fails: likely 1-hour expiry. Re-mint.
Authorization header ignored: verify the exact format Bearer <token> (single space, no extra quotes).

For per-endpoint auth requirements and try-it requests, see the API Reference.

Quickstart

Rate Limits & Plans