Developer documentation
Omegabuild OAuth 2.0
Connect an application to a player's public Omegabuild profile with the OAuth 2.0 authorization code flow.
Before you start
Create a client in OAuth clients. Omegabuild assigns a numerical client ID beginning at 10000, generates a client secret, and stores up to ten callback URLs for the client.
Keep the secret on your server. It is shown only once and must never be included in browser code or a public repository.
1. Send the player to authorize
Direct the player to /oauth/authorize with these query parameters:
| Parameter | Value |
|---|---|
response_type | code |
client_id | Your numerical client ID |
redirect_uri | One exact callback URL registered for this client |
scope | profile, or profile email to also request the user's private email claims |
state | A random value your app validates after the redirect |
/oauth/authorize?response_type=code&client_id=10000&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=profile&state=RANDOM_VALUEScopes and returned claims
| Scope | Consent | /api/oauth/userinfo response |
|---|---|---|
profile | Public Omegabuild profile | sub, preferred_username, account_type, classicube_linked, classicube_username, rank, rank_details, active_punishments, about_me, and created_at. |
profile email | Everything in profile, plus the user's verified email address | All profile claims plus email and email_verified. If the user has no confirmed address, email is null and email_verified is false. |
The profile scope is always required. The email address is private and is never returned unless the user approves profile email.
Client owners may additionally require an account to have a verified email address before authorization. This is an eligibility check; it does not grant access to the address unless the client also requests profile email.
2. Exchange the code
After approval, Omegabuild redirects to the exact requested registered callback URL with code and state. Verify state, then send a server-side POST request to /api/oauth/token using that same redirect_uri.
grant_type=authorization_code
client_id=10000
client_secret=YOUR_CLIENT_SECRET
code=AUTHORIZATION_CODE
redirect_uri=https://example.com/oauth/callbackThe response contains a bearer access_token, token_type, expires_in, and the granted scope. Client credentials may also be sent with HTTP Basic authentication.
3. Read the profile
Call GET /api/oauth/userinfo and send the access token in the authorization header.
Authorization: Bearer ACCESS_TOKENThe profile response includes the player ID, username, website rank, about-me text, and account creation date. Request profile email to receive the email claims described above.
Security and errors
- Use HTTPS callback URLs in production. HTTP is accepted only for localhost development.
- Callback URLs must match the registered value exactly.
- Authorization codes are single-use and expire after a short period.
- Access tokens expire after one hour. A rejected request returns an error such as
invalid_client,invalid_grant, orinvalid_token. - Delete a client to revoke its outstanding authorization codes and access tokens.