Single Sign-On via Link (SSO)
CapData offers two Single Sign-On (SSO) endpoints to log into the web portal via a link. These endpoints are not for programmatic API consumption; they are intended for interactive user access (e.g., opening the panel from your own system with a single click).
key parameter contains your credential (API Key or Agent Token).
Treat it like a password. Do not expose it in public HTML or on the frontend; preferably,
perform a 302 redirect from your backend to keep the key hidden.
Available Endpoints
GET /auth/apikey-login?key=API_KEY
Logs in as a Client (Owner) or Agency using the account's API Key. If the account is active, a session is created, and the user is automatically redirected to the first accessible section (dashboard, calendar, AI chat, etc.) based on permissions.
Parameters
key(required): The API Key of the Owner or Agency.
Example (direct link)
https://capdata.es/auth/apikey-login?key=YOUR_API_KEYBehavior
- Method:
GET - Typical response:
302 Found→ redirection to the corresponding panel. - In case of an invalid key or inactive account: redirection to the login page with an informational message.
- Does not consume tokens.
GET /auth/agent-apikey-login?key=AGENT_TOKEN
Logs in as an Agent (EmployeeToken) using their agent token. The session is associated with the client (Owner or Agency) to which the agent belongs and redirects to the agent's panel.
Parameters
key(required): The Agent's Token (EmployeeToken).
Example (direct link)
https://capdata.es/auth/agent-apikey-login?key=THE_AGENT_TOKENBehavior
- Method:
GET - Typical response:
302 Found→ redirection to the agent's panel. - Requirements: the agent must be active, and the associated main account must also be active.
- Does not consume tokens.
Recommended Usage (Keeping the Key Hidden)
To avoid exposing the API Key or Token in the browser's HTML, perform the SSO from your backend: your server builds the SSO URL with the key stored on the server and issues a 302 redirect to the user.
Example in Node/Express
app.get("/open-capdata", (req, res) => {
// The API Key is read from environment variables or a secure backend store
const API_KEY = process.env.CAPDATA_API_KEY;
const url = `https://capdata.es/auth/apikey-login?key=${encodeURIComponent(API_KEY)}`;
return res.redirect(302, url);
});Example in Python/Flask
import os
from flask import Flask, redirect
app = Flask(__name__)
@app.get("/open-capdata")
def open_capdata():
api_key = os.environ["CAPDATA_API_KEY"]
url = f"https://capdata.es/auth/apikey-login?key={api_key}"
return redirect(url, code=302)/open-capdata) and perform the redirect with the server-stored key there.
This way, the credential never appears in the client's HTML.
Best Practices and Security
- Treat the key like a password: do not include it in the frontend or in public repositories.
- Use backend redirects: avoid direct links with the key in emails or web pages.
- Revocation/rotation: if you suspect exposure, deactivate/rotate the API Key or Agent Token from the portal.
- Scope of access: SSO grants access to everything that account allows; review permissions before sharing links.
- Always use HTTPS: only use
httpsURLs to prevent leaks over plaintext traffic.
FAQ
Does the SSO link expire?
There is no automatic expiration: the link works as long as the API Key (or Agent Token) is valid and the account is active. If you rotate or deactivate the credential, existing links will stop working.
Does logging in via SSO consume tokens?
No. SSO only establishes the web session. Tokens are consumed when using services like AI Chat, extraction, or transcription.
Can I limit the scope (permissions) of the SSO?
No. The access will reflect the native permissions of the account or agent you are authenticating.
Is it valid for APIs?
No. To invoke APIs, use the authentication headers (e.g., X-CapData-Token).
SSO is exclusively for logging into the web portal.