Skip to main content

Authentication

The API uses OAuth 2.0 bearer tokens. You create a long-lived refresh token once in the AlphaSense web app. Your code exchanges it for a short-lived access token and sends that token with every request.

1. Get your credentials​

  1. Sign in to research.alpha-sense.com.
  2. Open Preferences, then API Keys.
  3. Copy the Client ID and Client Secret.
  4. Click Generate Refresh Token, confirm your identity, and copy the new token.

Copy the token itself, not the Refresh Token ID. The Expires At column shows when it stops working. The SuperAnalyst API does not use the API Key value on that page.

If you don't see the API Keys page, ask your account team to enable API access, SuperAnalyst, and SuperAnalyst API access for your user.

2. Get an access token​

Send your credentials to the token endpoint as a form:

POST https://auth.research.alpha-sense.com/oauth/token
import os
import requests

response = requests.post(
"https://auth.research.alpha-sense.com/oauth/token",
data={
"grant_type": "refresh_token",
"client_id": os.environ["ALPHASENSE_CLIENT_ID"],
"client_secret": os.environ["ALPHASENSE_CLIENT_SECRET"],
"refresh_token": os.environ["ALPHASENSE_REFRESH_TOKEN"],
},
)
response.raise_for_status()
access_token = response.json()["access_token"]

The response looks like this:

{"access_token": "<access token>", "token_type": "Bearer", "expires_in": 1800}

The access token lasts expires_in seconds, about 30 minutes. The response can also include a new refresh_token. When it does, the new one replaces your old one: save it and use it next time.

Send the token request once

If the request fails, check your credentials before you try again. Repeated attempts with a wrong client secret can lock the client out.

Already using the Agent API?

An access token from the Agent API password grant also works with the SuperAnalyst API. For new integrations, use the refresh token flow above: it needs no password or API key.

3. Call the API​

Send the access token in the Authorization header. No other auth headers are needed.

curl -sS "https://api.research.alpha-sense.com/superanalyst/v1/superanalysts/default/sessions?limit=1" \
-H "Authorization: Bearer $ACCESS_TOKEN"

A 200 response means your token and entitlements work.

Keep tokens fresh​

In a long-running service, cache the access token and renew it shortly before it expires. Renew one request at a time. Parallel renewals all spend the same refresh token, and a rotated refresh token works only once.

import os
import threading
import time
import requests


class TokenProvider:
def __init__(self):
self._refresh_token = os.environ["ALPHASENSE_REFRESH_TOKEN"]
self._access_token = None
self._expires_at = 0.0
self._lock = threading.Lock()

def headers(self):
with self._lock:
if time.time() > self._expires_at - 60:
self._renew()
return {"Authorization": f"Bearer {self._access_token}"}

def _renew(self):
response = requests.post(
"https://auth.research.alpha-sense.com/oauth/token",
data={
"grant_type": "refresh_token",
"client_id": os.environ["ALPHASENSE_CLIENT_ID"],
"client_secret": os.environ["ALPHASENSE_CLIENT_SECRET"],
"refresh_token": self._refresh_token,
},
)
response.raise_for_status()
token = response.json()
self._access_token = token["access_token"]
self._expires_at = time.time() + token["expires_in"]
# Also store a rotated refresh token in your secret store.
self._refresh_token = token.get("refresh_token", self._refresh_token)

Call tokens.headers() before each request. An open stream keeps working after its token expires.

Entitlements​

Each API user needs SuperAnalyst and SuperAnalyst API access. Without either one, requests return 403 ENTITLEMENT_REQUIRED. Your account team enables both, and a change can take a few minutes to apply.

Each user sees only their own sessions and files. Another user's session returns 404.

When authentication fails​

What you seeCauseFix
access_denied from the token endpointWrong client ID or secretStop. Re-copy both from the API Keys page, then try once.
invalid_grant from the token endpointRefresh token expired, revoked, or rotatedGenerate a new refresh token on the API Keys page.
401 UNAUTHENTICATED from the APIAccess token missing, expired, or invalidGet a new access token. Send Authorization: Bearer <token>.
403 ENTITLEMENT_REQUIRED from the APIAn entitlement is missingAsk your account team to enable it.

The API does not say why it rejected a token. If a fresh token still gets 401, contact support with the request_id from the error.

Keep credentials safe​

  • Load secrets from environment variables or a secrets manager. Never commit them.
  • Never log tokens. Log the request_id instead.
  • If a refresh token leaks, generate a new one and stop using the old one.