Signing in to Ads Control

Email and password

1. Sign in with your @firsteconomy.com email (you can type just your name) and your password.
2. Your admin creates your account and gives you a temporary password. You choose your own at first sign-in.
3. Forgot it? Ask your admin to reset it. You get a new temporary password and change it again.

Admins create accounts and reset passwords in the section "For admins" below. Send the temporary password privately, never in a group chat.

How to find your access key

1. Ask your admin. Keys are created by the person who runs Ads Control for your team. There is no sign-up page, and keys are never emailed or self-service.
2. Your admin creates your account and sends you the key privately, for example in a direct message or through a password manager. It looks like Xr4kT0q…, about 43 characters long.
3. Paste it into the sign-in screen and select Sign in.
4. Save the key in your password manager. The admin can see it only at the moment it is created: it is shown only once and is never stored on the server.

This is not a Google Ads or Meta key. Do not paste your Google, Meta or company login here, and never share your access key with anyone, including colleagues.

Lost your key, or think someone else has it?

Ask your admin to issue a new one. Your old key stops working the moment the new one is created. Nothing else about your account changes.

How the key works

• When you sign in, your browser sends the key once over the secure connection. The server compares a fingerprint (a SHA-256 hash) of what you typed with the fingerprint saved for your account. The key itself is never saved anywhere on the server.
• If it matches, the browser gets a sign-in cookie that lasts 12 hours. Page scripts cannot read it. After 12 hours, or after you select Sign out, you sign in again with the same key.
• Everything you approve, run or roll back is recorded under your name. That is why each person needs their own key, and why you cannot approve a change you proposed yourself.
• After 5 wrong attempts from the same network within 15 minutes, sign-in pauses for 15 minutes.
• If your admin removes your account, access ends immediately, even if you are signed in.

For admins: creating accounts, passwords and keys

Day to day, admins add people, reset passwords, change roles and choose which clients each person can use on the Team page in the app. The python -m auth.manage commands below still work on the server (on your own computer, use ./run.sh add-user; see the last section).

Run these on the server as the service user (see docs/deploy-ubuntu.md, step 4). Each command prints a temporary password or key once; send it to the person privately.

People sign in with email and password. Create an account (only @firsteconomy.com addresses; NAME is enough) or reset a forgotten password:

sudo -u adscontrol bash -c 'cd /opt/ads-control && set -a; . /etc/ads-control/ads-control.env; set +a; \
  /opt/ads-control/.venv/bin/python -m auth.manage add-email-user NAME employee'   # new person (or: admin)

sudo -u adscontrol bash -c 'cd /opt/ads-control && set -a; . /etc/ads-control/ads-control.env; set +a; \
  /opt/ads-control/.venv/bin/python -m auth.manage reset-password NAME'              # forgotten password

Access keys are for scripts that call the web API (they send Authorization: Bearer with the key). The MCP server is a separate, admin-only tool that runs locally and does not use these keys.

sudo -u adscontrol bash -c 'cd /opt/ads-control && set -a; . /etc/ads-control/ads-control.env; set +a; \
  /opt/ads-control/.venv/bin/python -m auth.manage add-user NAME employee'   # new person (or: admin)

sudo -u adscontrol bash -c 'cd /opt/ads-control && set -a; . /etc/ads-control/ads-control.env; set +a; \
  /opt/ads-control/.venv/bin/python -m auth.manage reset-key NAME'          # lost or leaked key

sudo -u adscontrol bash -c 'cd /opt/ads-control && set -a; . /etc/ads-control/ads-control.env; set +a; \
  /opt/ads-control/.venv/bin/python -m auth.manage list-users'              # who has access

To remove someone, open the Team page, select the person and choose Remove. Their access ends on their next request. Do not edit the users file by hand.

Testing on your own computer

If you started Ads Control with ./run.sh, a local admin key was created for you. Show it again with:

./run.sh key

Add a password user or reset a password locally:

./run.sh add-user NAME admin
./run.sh reset-password NAME

Using the key from scripts

Programs can send the same key in a header instead of signing in:

curl -H "Authorization: Bearer YOUR_KEY" https://your-ads-control-host/api/capabilities