Authentication¶

Every request requires an API token issued by Pacifico Research. The client sends the token in the HTTP x-api-key header; it does not perform an interactive login or token refresh.

Token input modes¶

The first token argument accepts three forms.

Explicit token file¶

import pacifico

data = pacifico.request("token.key", ticker="CHILE")

A string ending exactly in .key or .txt is treated as a local path and the entire file is read.

Default token file¶

data = pacifico.request(ticker="CHILE")

An omitted or empty token makes the client read token.key from the current working directory.

Direct token value¶

import os

import pacifico

token = os.environ["PACIFICO_API_TOKEN"]
data = pacifico.request(token, ticker="CHILE")

Any non-empty string that does not end in lowercase .key or .txt is treated as the token itself.

Recommended local setup¶

1. Create token.key outside shared or synchronized directories when practical.
2. Store only the token characters in the file.
3. Exclude token.key and other credential extensions from version control.
4. Restrict file permissions to the user running the integration.
5. Pass the explicit path in scripts whose working directory can vary.

On macOS or Linux:

chmod 600 /secure/path/token.key

Then:

data = pacifico.request(
    "/secure/path/token.key",
    ticker="BCP0600323",
)

Production and CI¶

Use the secret manager provided by the deployment platform and inject the value at runtime:

import os

import pacifico


def load_values(ticker):
    token = os.environ["PACIFICO_API_TOKEN"]
    return pacifico.request(token=token, ticker=ticker)

Do not print the token, include it in exception context, persist it in notebook output, or place it in command history. Treat result URLs and downloaded payloads as sensitive when the requested data is licensed.

File-path detection details¶

Token file detection is suffix-based and case-sensitive:

Input	Interpretation
""	Read ./token.key
"secrets/client.key"	Read that file
"secrets/client.txt"	Read that file
"secrets/client.KEY"	Treat the literal string as a token
"token.pem"	Treat the literal string as a token

There is no path existence check before reading. Missing .key or .txt files raise FileNotFoundError locally.

Rotation¶

When a token is exposed or a team member's access changes:

1. Revoke or rotate it through Pacifico Research.
2. Update the secret manager or token file.
3. Remove the value from source, notebook cells and outputs, logs, build artifacts, and shell history.
4. Rewrite repository history if it was committed; deleting the current file alone is insufficient.
5. Validate the replacement with a narrow metadata or single-ticker request.

Authentication troubleshooting¶

The transport layer does not explicitly interpret HTTP status codes before the delivery step. Authentication failures may therefore appear as a parsing error row, a JSON error object, an invalid polling URL, or an exception from requests.

For diagnosis, temporarily request raw JSON:

response = pacifico.request(
    os.environ["PACIFICO_API_TOKEN"],
    ticker="CHILE",
    format="json",
)
print(response)

Sanitize the output before sharing it. Never include the token itself. See Errors and troubleshooting for the full diagnostic sequence.