Authentication

Every request to the DealDome API must be authenticated. There are two ways to do this: JWT tokens for team members who log in with email and password, and API tokens for services and external integrations. Both are passed via the Authorization header.

POST/auth/login

JWT token

JWT tokens are the primary authentication method for team members. You obtain one by posting your email and password to the login endpoint. Tokens are valid for 24 hours and grant full access to every endpoint based on your team role.

Request body

Name
email
Type
string
Description
The email address associated with your DealDome account.
Name
password
Type
string
Description
Your account password.

Response

Name
token
Type
string
Description
A signed JWT token to use in subsequent requests.
Name
expires_at
Type
timestamp
Description
ISO 8601 timestamp indicating when the token expires (24 hours from issue).
Name
user
Type
object
Description
The authenticated user object containing id, email, and role.

Request

POST

/auth/login

curl -X POST https://api.dealdome.eu/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@dealdome.eu",
    "password": "your-password"
  }'

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-04-14T12:00:00Z",
  "user": {
    "id": "usr_9kLm3nOpQ",
    "email": "you@dealdome.eu",
    "role": "admin"
  }
}

Once you have a token, include it in every request as a Bearer token:

Using a JWT token

curl https://api.dealdome.eu/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

JWT tokens expire after 24 hours. If you receive a 401 Unauthorized response, request a fresh token by logging in again. Do not hardcode tokens in your application — always fetch them dynamically.

GET/products

API token

API tokens are designed for service-to-service integrations, CI/CD pipelines, and automated scripts. Unlike JWT tokens, API tokens do not expire automatically and can be scoped to specific permissions.

All API tokens are prefixed with dd_ so they are easy to identify. When you create an API token, you receive the raw token exactly once — the server stores only a SHA-256 hash, so the original value cannot be recovered.

Using an API token

Pass the token in the Authorization header with the Bearer scheme, exactly the same way you would use a JWT token:

Using an API token

curl https://api.dealdome.eu/products \
  -H "Authorization: Bearer dd_live_a1b2c3d4e5f6..."

JavaScript

const products = await fetch('https://api.dealdome.eu/products', {
  headers: {
    Authorization: 'Bearer dd_live_a1b2c3d4e5f6...',
  },
}).then((res) => res.json())

Store API tokens securely — treat them like passwords. If you suspect a token has been compromised, revoke it immediately from the dashboard or via the DELETE /auth/tokens/:id endpoint. The server only stores hashed tokens, so a database leak will not expose raw credentials.

Create token

POST

/auth/tokens

curl -X POST https://api.dealdome.eu/auth/tokens \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline",
    "scopes": ["products:read", "stats:read"]
  }'

Response

{
  "id": "tok_7xRm4pQsT",
  "name": "CI Pipeline",
  "token": "dd_live_a1b2c3d4e5f6g7h8i9j0...",
  "scopes": ["products:read", "stats:read"],
  "created_at": "2026-04-13T10:30:00Z"
}

Permission scopes

API tokens use permission scopes to control what a token can access. When creating a token, specify one or more scopes from the table below. JWT tokens for team members always have full access based on their role, so scopes only apply to API tokens.

Scope	Description
`financials:read`	Read daily financials, P&L reports, and financial summaries
`financials:write`	Create and update daily financial records and fixed costs
`products:read`	List and view products, cost prices, and inventory
`products:write`	Create, update, and delete products
`stats:read`	Access product performance metrics and ad spend data
`admin`	Full access to all endpoints, including user management and settings

The admin scope grants unrestricted access to the entire API. Only assign it to tokens that genuinely need it — for most service integrations, a combination of read scopes is sufficient.

Scope examples

A token with products:read and stats:read can fetch the product catalogue and performance metrics, but cannot modify any data. If it tries to create a product, the API returns a 403 Forbidden response:

403 response

{
  "error": "forbidden",
  "message": "Token does not have the required scope: products:write"
}