User API

Accounts and access tokens: signing up with an emailed code, logging in, carrying the token, and what your account can then do in the registry.

Reads are public: the catalog, the versions and the downloads need no credential at all, so an IDE that only installs extensions never has to ask anyone to sign in. Everything on this page is for the other case — publishing. You need an account to put an extension into the registry, and this is how you get one and prove it is yours. For what you then do with it, see the Extension API.

Two kinds of request

Reads need nothing at all. A token is what turns a caller into somebody: it identifies your account, and through it the extensions you own. See the Extension API for what you can then do with them.

1. Sign up

Anyone can create an account, but it is not usable until the address on it is confirmed. Sign-up mails a four-digit code; entering that code is what turns the account on — and logs it in, since by then its holder has proved both the password and the address.

curl -X POST "https://tucan.amlang.net/api/users/signup" \
  -H 'Content-Type: application/json' -d '{
    "username":    "anders",
    "email":       "anders@example.com",
    "password":    "correct horse battery staple",
    "displayName": "Anders"
  }'

{"username":"anders","email":"anders@example.com","verification":"sent","expiresIn":1800}

Then, with the code from the mail — the response is the same token a login returns:

curl -X POST "https://tucan.amlang.net/api/users/verify" \
  -H 'Content-Type: application/json' -d '{"username":"anders","code":"2452"}'

# a fresh code, which replaces the outstanding one
curl -X POST "https://tucan.amlang.net/api/users/verify/resend" \
  -H 'Content-Type: application/json' -d '{"username":"anders"}'

• username is 3-32 of A-Za-z0-9._-, because it ends up in URLs; password is at least 8 characters; email must be unique. A taken username or address is a 409 — sign-up cannot hide whether a name is free, since that answer is the point of the call.
• The code lives 30 minutes and dies after five wrong guesses. Four digits is 10,000 possibilities, so the cap is what makes it safe: a locked code is dead rather than merely disfavoured, and the way out is a new one, which is a new number to find. Resends are limited to one a minute per account, sign-ups to five an hour per IP address.
• Until the code is entered the account grants nothing. It holds no roles, owns no extensions, and its password is not a credential: /users/login answers 403 with "verification":"required" rather than a token.

2. Log in

curl -X POST "https://tucan.amlang.net/api/users/login" \
  -H 'Content-Type: application/json' \
  -d '{"username":"anders","password":"correct horse battery staple"}'

{
  "accessToken":      "eyJhbGciOiJIUzI1NiJ9…",
  "tokenType":        "Bearer",
  "expiresIn":        86400,
  "refreshToken":     "Yy0xQk9…",
  "refreshExpiresIn": 31536000,
  "username":         "anders",
  "roles":            ["Administrator"]
}

Two tokens, with two jobs. The access token goes on every request and lasts 24 hours; it cannot be called back, which is why it is short. The refresh token lasts a year, is sent to one endpoint only, and can be called back — so a lost machine is a revoked session rather than a password change.

Every failure — unknown user, wrong password, disabled account, no password set — returns the same 401 and the same message. That is deliberate: distinguishing them tells an attacker which usernames exist. The one exception is an unverified account, which answers 403 with "verification":"required": that is only reachable with the right password, so it reveals nothing the caller did not just prove they knew, and it is the difference between retrying the password and going to read the mail.

3. Stay logged in

curl -X POST "https://tucan.amlang.net/api/users/token/refresh" \
  -H 'Content-Type: application/json' -d '{"refreshToken":"Yy0xQk9…"}'

The reply is the same shape as a login: a new access token and a new refresh token. Store both — the one you sent is spent.

• Refresh on a schedule, not on a 401. Halfway through the access token's life is a good rule: twice a day against a 24-hour token leaves a wide margin for a machine that was switched off, or a clock that is off.
• Rotation is the point. Every refresh consumes the token and issues its replacement, so a stolen copy works only until you next refresh. When a spent token is presented again, the whole session is revoked on the spot — one of the two callers holding it is not you, and there is no telling which, so both stop. A 401 with "refresh":"rejected" means log in again.
• A retry is safe. If the reply is lost in transit, sending the same token again within two minutes counts as the same refresh rather than as reuse, so a dropped connection is not a forced logout.
• Keep it like a password. It is a bearer credential with a year on it: store it where you would store one, never in a project folder that might be committed, and never log it.

To end a session deliberately, and to see what is signed in:

curl -X POST "https://tucan.amlang.net/api/users/logout" \
  -H 'Content-Type: application/json' -d '{"refreshToken":"Yy0xQk9…"}'

curl "https://tucan.amlang.net/api/users/me/sessions" -H "Authorization: Bearer $ACCESS_TOKEN"
curl -X DELETE "https://tucan.amlang.net/api/users/me/sessions/12" -H "Authorization: Bearer $ACCESS_TOKEN"
curl -X DELETE "https://tucan.amlang.net/api/users/me/sessions"    -H "Authorization: Bearer $ACCESS_TOKEN"

One row per machine signed in as you: what asked for it, where it was last used from, when it expires. The name shown is the User-Agent the login came with, so send something a person will recognise. An access token already issued stays valid until it runs out — nothing can recall it — which is exactly why its life is measured in hours.

4. Pass the token

curl "https://tucan.amlang.net/api/users/me" -H "Authorization: Bearer $ACCESS_TOKEN"

# and what that account participates in, invitations included
curl "https://tucan.amlang.net/api/users/me/extensions" -H "Authorization: Bearer $ACCESS_TOKEN"

The Bearer prefix is optional but conventional, and a token cookie is accepted as a fallback for browser clients. GET /users/me returns the account the token names — the cheapest way to check that a token is still good and see its roles.

What is in the token

HS256, signed by the registry.

{
  "sub":                "75",
  "preferred_username": "anders",
  "roles":              ["Administrator"],
  "iat":                1788282039,
  "exp":                1788325239,
  "iss":                "https://tucan.amlang.net/api",
  "aud":                "amlang-registry"
}

• preferred_username is the link to the account. It is matched against User.username; if no account matches, the token authenticates but resolves to nobody, and account-scoped endpoints return 404.
• Roles are a snapshot. They are copied in at login, so changing someone's roles takes effect on their next token, not immediately. Keep lifetimes short if that matters to you.
• Expiry is enforced, 24 hours by default (expiresIn is in seconds). Past that, refresh rather than log in again.
• An access token cannot be revoked: ending a session stops it being renewed, and the token already issued runs out its 24 hours. Treat one the way you would a password.

What each code means

What your account can do

Once you are signed in and verified, the registry is open to you: you can create an extension, and you own what you create.

Answering an invitation is yours alone: an extension's owner can invite you, but only you can accept. Anyone else trying gets a 403.

Endpoints