API Quickstart

Go from nothing to a working API call in about five minutes: register an API client, trade its credentials for an access token, and read a profile.

An API client acts as your application itself. It is the right tool for backends, bots, and scripts. To act on behalf of a signed-in RemiliaNET user instead (reading their stats, automating chat, etc), you want a login client. See the Login Quickstart for more.

1. Register your API client

1. Sign in at https://www.remilia.net and open the developer portal from your profile menu.
2. Create an application and pick the API key (confidential) client type.
3. Select the scopes you need. See Scopes.
4. Submit. Your application page shows the assigned client ID immediately, and reveals the client secret once the application is approved.

Treat the secret like a password: keep it out of source control, shell history, and logs.

2. Load your credentials

export REMILIA_CLIENT_ID="your-client-id"
read -rs REMILIA_CLIENT_SECRET   # paste the secret; it is not echoed
export REMILIA_CLIENT_SECRET

Avoid set -x and curl -v while these are set — both print the secret and the Authorization header.

3. Get an access token

Ask the token endpoint for a token with the client_credentials grant:

ACCESS_TOKEN=$(curl --fail-with-body -sS \
  https://www.remilia.net/oidc/realms/remilia/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id="$REMILIA_CLIENT_ID" \
  --data-urlencode "client_secret=$REMILIA_CLIENT_SECRET" \
  | jq -er '.access_token')

The response fields you care about:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300
}

• access_token — the bearer token you send on API requests.
• expires_in — its lifetime in seconds.

Reuse the token until it is close to expiring, then repeat this call — do not fetch one per request. There is no refresh token for Client Credentials.

If the call fails with invalid_client, the application is not approved yet or the ID and secret do not match.

4. Make your first request

GET /users/{username} returns a user's public profile.

curl --fail-with-body -sS \
  https://www.remilia.net/api/v1/users/remilia \
  -H "Authorization: Bearer $ACCESS_TOKEN"

You should see the profile object.

{
  "user": {
    "username": "remilia",
    "displayName": "Remilia",
    "bio": "...",
    "location": "...",
    "pfpUrl": "..."
  },
  "achievementContext": {},
  "viewerContext": { "areFriends": false }
}

Every other endpoint works the same way. Browse Endpoints to see what's available.

Common errors

Status	error.code	When
401	invalid_token	The bearer token is invalid or expired — request a new one
401	unauthorized	A scoped endpoint was called with no token
403	insufficient_scope	The token lacks a scope the endpoint requires
403	requires_user	The endpoint acts for a user; the token carries the scope but has no user attached — use a login client
403	forbidden	The account is disabled, or the action is not permitted
404	not_found	No such endpoint under /api/v1, or no such user profile
405	method_not_allowed	Wrong HTTP method for the path
500	internal_error	Something failed on our side — oops! safe to retry with backoff