Authentication

Public or signed in

Most of the API is public and needs nothing. Endpoints that act for a person need a bearer token in the Authorization header:

GET /v1/me HTTP/1.1
Host: api.alloymc.dev
Authorization: Bearer <token>

Without a valid token they answer 401 with the code unauthorized. The reference marks these endpoints with token.

Tokens are never put in cookies or URLs, so they can't leak through links or other sites.

Who can get a token today

Right now only Alloy, the launcher, can sign people in and receive tokens. The flow below is documented so you can see exactly what happens with your account. Apps of your own, with their own consent screen and limited scopes, are the next thing on the developer roadmap.

How Alloy signs you in

Alloy uses a one-time code with PKCE, the same idea OAuth uses for apps that can't keep a secret. Your password is only ever typed on alloymc.dev, never into Alloy.

1. Alloy makes a secret. It creates a random verifier and its SHA-256 hash, the challenge, encoded as base64url without padding.
2. Alloy opens your browser at https://alloymc.dev/auth/app?challenge=<challenge>&state=<random>&device=<name>. You sign in there if needed and see who's asking, for example "Alloy on Sam's PC".
3. You choose Allow. The browser hands a one-time code back to Alloy through alloy://auth?code=<code>&state=<state>. Alloy checks that state is the one it sent.
4. Alloy trades the code for a token, proving it made the challenge:

curl -X POST https://api.alloymc.dev/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"code": "<code>", "verifier": "<verifier>"}'

{
  "token": "<token>",
  "tokenType": "Bearer",
  "user": { "handle": "kestrel", "displayName": "Kestrel" }
}

A code works once, for a few minutes, and only with the matching verifier. Someone who intercepts the redirect can't use it.

How long tokens last

A token stays valid while it's used and ends after 90 days without use. You can see every signed-in device on your account page and sign any of them out. Changing your password signs out everything else.

To sign a token out from the app itself:

curl -X DELETE https://api.alloymc.dev/v1/auth/token -H "Authorization: Bearer <token>"

Keeping tokens safe

• Store tokens where the operating system protects them, like the system keychain.
• Send them only to https://api.alloymc.dev.
• If a token leaks, sign it out under Devices. Found a security problem? Write to security@elchi.dev.