Authentication

The Semantico API authenticates requests with a bearer token in the Authorization header:

Authorization: Bearer <token>

There are two kinds of token. For integrations, scripts, and server-to-server access, use a long-lived API token. For interactive sessions, use a standard JWT obtained by logging in.

API tokens (recommended for integrations)

An API token is a long-lived, non-expiring credential scoped to your workspace.

• Full access to your workspace’s product endpoints.
• No expiration — it stays valid until revoked.
• Revocable at any time.

Getting a token

API tokens are issued by Semantico. Contact your account manager or support to request one. For security, the full token value is shown only once at creation — store it somewhere safe immediately.

Using a token

Send it as a bearer token on every request:

# List products
curl -H "Authorization: Bearer <your-api-token>" \
  https://api.semantico.ai/api/v1/products/

# Create a product
curl -X POST \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"sku": "PROD-123"}' \
  "https://api.semantico.ai/api/v1/products/?locale=en-US"

In Python:

import requests

API_TOKEN = "<your-api-token>"
BASE_URL = "https://api.semantico.ai/api/v1"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json",
}

# Get products
products = requests.get(f"{BASE_URL}/products/", headers=headers).json()

# Create a product
data = {"sku": "NEW-SKU", "name": "Acme water bottle 750ml"}
response = requests.post(f"{BASE_URL}/products/", json=data, headers=headers)

Keeping tokens safe

• Store tokens in environment variables or a secret manager — never in source control.
• Always use HTTPS.
• If a token is exposed, ask us to revoke it immediately and issue a new one.
• Request tokens with the minimum access your integration needs.

Login tokens (JWT)

If you’re building against an interactive session rather than a server integration, you can obtain a short-lived JWT by logging in with a user’s credentials.

Log in to receive an access and a refresh token:

POST /api/v1/login/
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Use the access token as the bearer token. Access tokens are valid for 7 days; when one expires, exchange the refresh token (valid 14 days) for a new access token:

POST /api/v1/refresh/
Content-Type: application/json

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

For most integrations, a long-lived API token is simpler and is the recommended choice.