---
title: "Register OAuth application"
method: POST
path: "/api/v1/sso/applications"
tags: ["SSO - Applications"]
---

# Register OAuth application

`POST /api/v1/sso/applications`

**Rate limit:** 60 requests per 60 seconds. This is the **default shared quota** — it is shared with every other endpoint that has no dedicated limit, so requests across those endpoints all draw from the same budget.

---

Creates a new OAuth application. The authenticated user automatically becomes the application admin. Both `clientId` and `clientSecret` are auto-generated server-side. The `clientSecret` is returned **only in this response** (one-time reveal) - subsequent reads will never expose it again, so callers must store it securely. Auto-populated defaults (audience, applicationType, supported flows, token expirations) come from service configuration. Validation is aligned with the upstream sts-metadata-api: `applicationName` max 100 chars, `applicationIconUrl` max 500 chars, each `redirectUri` max 500 chars and unique, each `scopeId` positive and recognized in the cached scope catalog.

## Headers

- `x-request-id` string, uuid, required
- `x-api-key` string, password, required
- `x-user-key` string, password, required

## Request body

- CreateApplicationBody
  - `applicationName` string, required — Display name shown to end users in the OAuth consent screen.
  - `applicationIconUrl` string, uri, required — Publicly reachable URL of the application icon. Format-validated only - the URL is not fetched by the service.
  - `scopes` ScopeItem[], required — Scopes that the application will request from end users. Each `scopeId` must be positive and present in the cached scope catalog. Duplicates are rejected.
    - `scopeId` integer, required — Scope identifier. Must be a known scope from `GET /api/v1/sso/scopes`.
    - `isMandatory` boolean, required — When true, the user cannot deselect this scope on the consent screen.
  - `redirectUris` string[], required — OAuth redirect URIs registered for the application. Must be unique. Each URI is capped at 500 characters.

## Response `201`

Application created successfully. The `clientSecret` is included once and only once.

- CreateApplicationResponse
  - `application` ApplicationItem — Full application record. The `clientSecret` is intentionally excluded.
    - `applicationId` integer — Internal numeric identifier of the application.
    - `applicationName` string — Display name of the application.
    - `applicationIconUrl` string, uri — URL of the application icon.
    - `clientId` string, uuid — OAuth client identifier. Stable across the lifetime of the application.
    - `audience` string — OAuth audience claim issued for tokens minted for this application.
    - `applicationType` string — OAuth application type (e.g. `public`, `confidential`).
    - `scopes` ApplicationScopeItem[] — Scopes assigned to the application, including which are mandatory at consent time.
      - `scopeId` integer — Scope identifier.
      - `isMandatory` boolean — When true, the user cannot deselect this scope on the consent screen.
    - `redirectUris` string[] — Registered OAuth redirect URIs.
    - `supportedFlows` string[] — OAuth flows supported by the application (e.g. `authorization_code`, `refresh_token`).
    - `supportedCodeChallengeMethods` string[] — PKCE code-challenge methods supported by the application (e.g. `S256`).
    - `ssoIdTokenExpirationInMinutes` integer — Lifetime of issued SSO id tokens, in minutes.
    - `ssoRefreshTokenExpirationInMinutes` integer — Lifetime of issued SSO refresh tokens, in minutes.
    - `ssoAccessTokenExpirationInMinutes` integer — Lifetime of issued SSO access tokens, in minutes.
    - `adminGcids` integer[] — GCIDs of users who can administer this application.
  - `clientSecret` string, uuid — OAuth client secret. Returned exactly once at creation time and never again - store it securely.

## Other responses

- `400` — Validation error - missing required field, malformed URL, duplicate redirect URI, unknown scope id, or duplicate scope ids.
- `401` — Missing or invalid STS access token.
- `429` — Too Many Requests — the shared rate limit (60 requests / 60s) was exceeded.
- `500` — Backend sts-metadata-api unavailable.

---

[API](https://skmtc.net/etoro/apis/etoro-api.md) · [All operations](https://skmtc.net/etoro/apis/etoro-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/etoro/etoro-api/revisions/69c1fb266c35/schema)