Authentication
How API tokens work: the header, expiry, allowed IPs, server and site limits, and what 401 and 403 mean.
Send the token
Every request carries the token as a bearer token:
curl -H "Authorization: Bearer mf_YOUR_TOKEN" https://YOUR-MYFORGE/api/v1/token
The only public endpoint is GET /api/v1/openapi.json (the API description).
What a token is
- A token belongs to one person and one team. It acts as that person, in that team, and never has more rights than that person has right now.
- pfcloud stores only a fingerprint of the token. If you lose it, use New secret (same settings, new value) or make a new token.
- Tokens are made and revoked in the dashboard under API, then Tokens. The API cannot make tokens.
Settings you choose when you make a token
| Setting | What it does | Advice |
|---|---|---|
| Scopes | The rights the token has. See Scopes and permissions. | Tick only what the job needs. |
| Expiry | Required. After this time the token answers 401. The team owner can set a maximum (1 to 365 days). |
Days for AI tools, weeks for CI. |
| Allowed addresses | IP addresses or CIDR ranges (for example 203.0.113.7 or 203.0.113.0/24). From any other address the token answers 403. |
Use it whenever the caller has a fixed address. The team owner can make it required. |
| Limits | Only some servers and sites. A server includes all its sites. Anything outside the limit answers 404, as if it did not exist. |
Give an AI only the servers it needs. A token with limits cannot add servers. |
Check a token: GET /token
curl -s -H "Authorization: Bearer $TOKEN" https://YOUR-MYFORGE/api/v1/token
The data object contains:
| Field | Meaning |
|---|---|
id, name |
The token's public id and its name. |
team |
name and slug. |
acts_as |
The person (name, role) the token acts as. |
scopes |
Scopes the token has. |
usable_scopes |
Scopes that pass every check right now. |
blocked_scopes |
A map of scope to the reason it is blocked (plan, owner rule, or missing permission). Empty when nothing is blocked. |
limited_to |
The server and site limits, or null. |
allowed_ips |
The address list, or null. |
expires_at |
When it expires. |
requests_count |
How many calls it has made. |
Call this at the start of every integration and every AI session.
What the errors mean
| Status | Message (shortened) | Meaning |
|---|---|---|
401 |
Missing, wrong or expired API token | The header is missing or wrong, the token expired or was revoked. |
401 |
The person who made this token is no longer in the team | The token is dead. Make a new one. |
403 |
This token can't be used from <ip> |
The address is not in allowed_ips. |
403 |
The person who made this token must turn on two-factor authentication first | The team requires two-factor sign-in for its members. |
403 |
This token doesn't have the <scope> scope |
Add the scope (make a new token). |
403 |
The team's plan doesn't include <scope> |
Plan limit. Ask the team owner or support. |
403 |
The team owner switched <scope> off for API tokens |
Owner rule under API, then Rules. |
403 |
The token's maker no longer has the permission "..." | The person's role changed. A token cannot outgrow its maker. |
A token loses a right the moment the plan, the owner or the maker's role takes it away. Nothing needs to be changed on the token.
Good habits
- Store tokens in a secret manager or CI secret, never in code or chat. See AI security.
- One token per system, so you can revoke one without breaking others.
- Look at API, then Activity from time to time: the last 100 calls with token, call, answer and address.