Auth & Tokens

DealDome supports two authentication methods: JWT Bearer tokens (for user sessions) and API tokens (for programmatic access). JWTs are obtained by logging in with email and password. API tokens use the dd_ prefix and can be scoped to specific permissions, making them ideal for integrations and automations.

User and API token management endpoints require the admin scope. The login endpoint is unauthenticated.

Permission scopes

API tokens can be assigned one or more scopes to control access. Here's the full list:

Name
financials:read
Type
scope
Description
Read access to daily financials, ad spend, and product performance data.
Name
financials:write
Type
scope
Description
Write access to create and update financial records.
Name
products:read
Type
scope
Description
Read access to products and fixed costs.
Name
products:write
Type
scope
Description
Write access to create, update, and delete products and fixed costs.
Name
stats:read
Type
scope
Description
Read access to financial reports and KPI overviews.
Name
admin
Type
scope
Description
Full access including user management, API token management, and settings.

The API token model

API tokens are used for programmatic access. Each token has a name, a set of scopes, and a dd_ prefix for easy identification.

Properties

Name
id
Type
integer
Description
Unique identifier for the API token.
Name
name
Type
string
Description
A descriptive name for the token (e.g., "Shopify Sync", "Telegram Bot").
Name
prefix
Type
string
Description
The token prefix — always dd_. The full token is only shown once at creation.
Name
scopes
Type
array
Description
An array of permission scopes assigned to this token.
Name
last_used_at
Type
timestamp
Description
Timestamp of when the token was last used to make an API call.
Name
created_at
Type
timestamp
Description
Timestamp of when the token was created.

POST/auth/login

This endpoint authenticates a user and returns a JWT token. Use this token in the Authorization: Bearer {token} header for subsequent requests.

Required attributes

Name
email
Type
string
Description
The user's email address.
Name
password
Type
string
Description
The user's password.

Request

POST

/auth/login

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

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-04-14T09:00:00Z",
  "user": {
    "id": 1,
    "email": "user@dealdome.eu",
    "name": "Admin"
  }
}

GET/auth/users

List users

This endpoint returns all users in your DealDome account. Useful for managing team access.

Request

GET

/auth/users

curl https://api.dealdome.eu/auth/users \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "id": 1,
      "email": "admin@dealdome.eu",
      "name": "Admin",
      "role": "admin",
      "created_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "email": "va@dealdome.eu",
      "name": "Virtual Assistant",
      "role": "member",
      "created_at": "2026-02-15T10:00:00Z"
    }
  ]
}

POST/auth/users

Create a user

This endpoint lets you create a new user for your DealDome account.

Required attributes

Name
email
Type
string
Description
The email address for the new user.
Name
name
Type
string
Description
The display name for the user.
Name
password
Type
string
Description
The initial password for the user.

Optional attributes

Name
role
Type
string
Description
The user role — admin or member. Defaults to member.

Request

POST

/auth/users

curl https://api.dealdome.eu/auth/users \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"email": "va@dealdome.eu", "name": "Virtual Assistant", "password": "secure-password"}'

Response

{
  "id": 2,
  "email": "va@dealdome.eu",
  "name": "Virtual Assistant",
  "role": "member",
  "created_at": "2026-02-15T10:00:00Z"
}

GET/auth/api-tokens

List API tokens

This endpoint returns all API tokens for your account. The full token value is never returned — only the dd_ prefix is shown for identification.

Request

GET

/auth/api-tokens

curl https://api.dealdome.eu/auth/api-tokens \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "id": 1,
      "name": "Shopify Sync",
      "prefix": "dd_",
      "scopes": ["financials:read", "financials:write", "products:read"],
      "last_used_at": "2026-04-13T08:30:00Z",
      "created_at": "2026-01-10T12:00:00Z"
    },
    {
      "id": 2,
      "name": "Telegram Bot",
      "prefix": "dd_",
      "scopes": ["stats:read"],
      "last_used_at": "2026-04-13T07:00:00Z",
      "created_at": "2026-02-01T09:00:00Z"
    }
  ]
}

POST/auth/api-tokens

Create an API token

This endpoint creates a new API token. The full token value is returned only once in the response — make sure to copy it, because you won't be able to retrieve it again.

Required attributes

Name
name
Type
string
Description
A descriptive name for the token.
Name
scopes
Type
array
Description
An array of permission scopes to assign to this token.

Request

POST

/auth/api-tokens

curl https://api.dealdome.eu/auth/api-tokens \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shopify Sync", "scopes": ["financials:read", "financials:write", "products:read"]}'

Response

{
  "id": 1,
  "name": "Shopify Sync",
  "token": "dd_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "scopes": ["financials:read", "financials:write", "products:read"],
  "last_used_at": null,
  "created_at": "2026-01-10T12:00:00Z"
}

The token field is only included in the creation response. Store it securely — it cannot be retrieved later.

DELETE/auth/api-tokens/:id

Delete an API token

This endpoint revokes and permanently deletes an API token. Any integrations using this token will immediately lose access.

Request

DELETE

/auth/api-tokens/1

curl -X DELETE https://api.dealdome.eu/auth/api-tokens/1 \
  -H "Authorization: Bearer {token}"