Getting a token

Uely is an OAuth 2.1 authorization server. Registration is open, PKCE is required, and there are no client secrets.

Register

Dynamic client registration is public — no credential, no application form.

curl -s -X POST https://api.uely.ch/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "Your agent",
    "redirect_uris": ["http://localhost:8199/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
  }'

You get a client_id. There is no client secret — token_endpoint_auth_methods_supported is ["none"], and PKCE is what protects the exchange.

The client_name you choose is shown to the person on the consent screen, labelled as unverified, because you chose it yourself. Pick something they will recognise.

Send them to consent

https://api.uely.ch/oauth/authorize
  ?client_id=<your client_id>
  &redirect_uri=<your registered redirect>
  &response_type=code
  &code_challenge=<S256 of your verifier>
  &code_challenge_method=S256
  &state=<random, single-use>
  &scope=ask documents.read
  &resource=https://api.uely.ch/mcp

resource is what asks for the agent plane. Leave it out and you get an identity token, which every workspace tool will refuse.

Ask only for the scopes you need. The consent screen lists every one in plain German and marks the ones that write.

The scopes

Scope	What it grants
ask	Ask a question against the workspace and knowledge base
research	Research a question against the knowledge base and get a written report. Costs AKh; reads no workspace data
documents.read	Read documents, reports and measurements
training.write	Add sources to the knowledge base
contacts.read	Read contacts
places.read	Read places and fields
work_items.read	Read work items
listings.read	Read marketplace listings, including unpublished ones
animals.read	Read animals
letters.read	Read correspondence

Consent is shown every time. A stored grant is what makes revocation possible; it is never used to skip the screen.

Exchange the code

curl -s -X POST https://api.uely.ch/oauth/token \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d redirect_uri=<same redirect> \
  -d client_id=<client_id> \
  -d code_verifier=<your verifier>

{
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "ask documents.read",
  "access_token": "...",
  "refresh_token": "..."
}

Access tokens last 15 minutes. Refresh tokens rotate on use: the response carries a new one and the old one stops working. Replaying a rotated refresh token invalidates the whole family, so store the newest and only the newest.

Check what you got

Decode the access token and confirm:

• aud is https://api.uely.ch/mcp — not the userinfo audience
• client_id is present
• scope holds what you asked for

Then send it as Authorization: Bearer <token>.

Being disconnected

The person can revoke your access at any time from their settings, and it takes effect on your next request — not when the token expires. See Errors and limits.