Administrative REST API Configuration

The Administrative REST API is served by the Ember Monitor backend (and by the Ember Web Gateway) under the base path /api/admin/v1. This document describes how to enable it, authenticate clients and grant permissions. For the list of operations, see the Administrative API Reference.

caution

Administrative operations change production trading state. Use TLS, grant permissions to as few users as possible, and do not expose this API over the public Internet.

Enabling

The API is enabled by default. To turn it off, add the following to Ember Monitor's application.yaml (see Adding a Configuration File) and restart Ember Monitor:

admin:
  api:
    enabled: false

The API listens on the same host and port as Ember Monitor (server.port, 8988 by default). Enable HTTPS in the same way as for Ember Monitor, see Enabling HTTPS.

Authentication

The API has its own security chain, independent of the Ember Monitor UI session. It never uses cookies or sessions: every request must carry credentials. The mechanism is selected by the existing Ember Monitor security settings:

Configuration	How clients authenticate
security.oauth2.provider.name is set, or security.oauth2.authenticationType is PROVIDER	Bearer token (JWT) issued by your identity provider: Authorization: Bearer <token>
authenticationType is SIMPLE or LDAP and no provider is named	HTTP Basic against the user directory (uac-file-security.xml or uac-ldap-security.xml): Authorization: Basic <base64(user:password)>
authenticationType is NONE	The API is closed: every request is rejected

The API refuses to run without authentication. It is also closed when a token provider is expected but no JWT validation is configured (see below).

For more information on authentication types, see Authentication and Authorization.

Bearer tokens

Tokens are validated as an OAuth2 resource server (signature, expiry, issuer, and audience if configured). When the Monitor login provider is configured, its issuer-uri (or jwk-set-uri) is reused to validate tokens. To validate tokens explicitly, or when the token issuer differs from the address Ember uses to reach the provider, configure the Spring resource server:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://cognito-idp.us-east-2.amazonaws.com/us-east-2_xxxxx
          audiences: my-client-id     # optional; reject tokens issued for other audiences
          # jwk-set-uri: https://idp.example.com/.well-known/jwks.json

note

The security.oauth2.provider.audience and security.oauth2.provider.validateIssuer settings are no longer supported. Use spring.security.oauth2.resourceserver.jwt.audiences and the resource server issuer-uri instead.

Obtain a token with the client credentials grant (for service accounts) or any other flow supported by your provider, and refresh it before it expires.

HTTP Basic

When the API authenticates users against a directory, use users defined in uac-file-security.xml (authenticationType: SIMPLE) or uac-ldap-security.xml (authenticationType: LDAP). Always use TLS with HTTP Basic. The Ember Web Gateway Docker image and Helm chart set security.oauth2.authenticationType: SIMPLE by default.

Authorization

Read-only endpoints (all GET requests, and POST /positions which only queries) are available to any authenticated user. Operations that change state require an Ember Monitor permission. A user without it receives 403 Forbidden.

Permission	Operations
HALT_RESUME_TRADING	Halt and resume trading
CHANGE_RISK_LIMITS	Update risk case tables
POSITION_ADJUSTMENT	Adjust positions
ENABLE_DISABLE_SERVICE	Enable and disable services
CONTROL_FIX_SESSION	Enable, disable and disconnect FIX sessions

Where permissions come from depends on the authentication mode:

• Identity provider (authenticationType: PROVIDER) – permissions are taken from the authorities of the token. The authority name must be exactly the permission name, for example HALT_RESUME_TRADING. Configure authoritiesClaim and authorityMapping to map your provider's roles to permissions.
• User directory (SIMPLE or LDAP) – permissions are defined in uac-access-rules.xml.

Positions

Unlike REST/WS API clients, which can only see positions of their own order source, the Administrative API queries positions of all sources. This does not depend on the engine.allowUnrestrictedPositionRequests setting.