Authentication

The Eolymp API is served at https://api.eolymp.com. Credentials are passed in the Authorization header:

curl https://api.eolymp.com/runtime \
  -H "Authorization: Bearer etkn-..."

The credential is either an API key or an OAuth 2.0 access token, and it identifies the account it belongs to — an Eolymp admin, or a user of one space.

The choice between the two depends on who will be using the integration. An API key fits automation run by a single account, where nobody logs in and the code always acts as that account. OAuth 2.0 fits an application that other people sign in to with their own Eolymp accounts: a custom dashboard, a problem importer shared with colleagues, anything where the application acts as whoever is logged in.

Admins and users

Eolymp has two kinds of account, issued from two different places.

Admin accounts are used to manage spaces — writing problems, running contests, viewing internal scoreboards. They are Eolymp SSO accounts, managed centrally by the account service at accounts.eolymp.com, and they are used at console.eolymp.com.

User accounts are members scoped to a specific space — entering contests, submitting solutions, leaving comments. Every space configures its own authentication: it can accept sign-in with an Eolymp account, keep its own database of users, or delegate sign-in to a third-party SSO through OIDC or Google Workspace. Users see eolymp.com, or <space>.eolymp.space on a custom space.

A user account is therefore tied to the authentication method its space uses. Even when a space is configured to sign people in with their Eolymp account, the resulting token is issued by the space rather than by Eolymp SSO.

⚠️
The two are not interchangeable. An admin credential cannot submit a solution as a participant, and a user credential cannot edit a problem. An integration that does both needs one credential of each kind.

The role does not need to be declared in the request. The API determines it from the credential itself.

API keys

An API key is a credential tied to one account and a fixed set of scopes. There is no login flow and nothing to refresh, which makes it a good fit for scripts, cron jobs and CI.

Keys are created on the developer page for the role in question:

Admins: accounts.eolymp.com/developer
Users: eolymp.com/developer, or https://<space>.eolymp.space/developer on a custom space

An expiration is chosen when the key is created — 30 days, 90 days, 180 days or a year — which bounds how long the key stays valid and requires periodic rotation. For a first trial of the API, the shortest option is preferable: a key that expires in a month leaves nothing to clean up.

The secret is shown once, immediately after the key is created, so copy it somewhere safe before closing the dialog. If the secret is lost, delete the key and create a new one.

🔒
A key can do anything its account and scopes allow, so treat it like a password. Keep it on the server, and out of browsers, mobile apps and Git. For code running on someone else's device, use OAuth 2.0 instead.

OAuth 2.0

Eolymp SSO is a plain OAuth 2.0 and OpenID Connect server, so any standard client library works. The login flow contains nothing Eolymp-specific.

Read the endpoints from the discovery document rather than hardcoding them:

curl https://accounts.eolymp.com/.well-known/openid-configuration

It currently returns the following values:

Setting	Value
Issuer	`https://accounts.eolymp.com`
Authorization endpoint	`https://accounts.eolymp.com/authorize`
Token endpoint	`https://api.eolymp.com/oauth2/token`
User info endpoint	`https://api.eolymp.com/oauth2/userinfo`
Revocation endpoint	`https://api.eolymp.com/oauth2/revoke`
JWKS	`https://api.eolymp.com/oauth2/certs`
Grant types	`authorization_code`, `refresh_token`
PKCE	`S256`, `plain`

Use the authorization code flow with PKCE. Access tokens are short-lived, so request the offline_access scope as well: it yields a refresh token, which can be exchanged for a new access token whenever the current one expires.

Getting a client ID

Client registration is not self-service. Contact support to have a client created, and include the name of the application, the redirect URIs it will use, and the scopes it needs.

Scopes

Both kinds of credential are scoped. A scope has the form service:resource:action:

atlas:problem:read
atlas:problem:write
atlas:submission:write
community:member:read
judge:submission:read

Request only the scopes the integration needs. A call outside the credential's scopes is rejected even when the account behind it holds every permission. The full list of scopes appears when creating an API key, and the API Reference names the scopes each endpoint expects.