Auth and API-key ownership

Account sessions control API-key creation, listing, and revocation. API keys are tied to the signed-in account and are used by integrations to authenticate against supported Omen APIs and gateways.

API key lifecycle

Create, list, and revoke account-scoped credentials.

The create response returns plaintext once and stores only a SHA256 hash server-side. Existing-token list responses return metadata without plaintext values.

Token format: Plaintext keys use the `omn_` prefix and should be stored as secrets.
Permissions: Supported scopes are `read`, `trade`, and `withdraw`.

POST /auth/api-tokens
Authorization: Bearer <account access token>

{
  "label": "perps-prod-gateway",
  "permissions": ["read", "trade"],
  "password": "<current password when required>",
  "expires_in_secs": 2592000
}

Account sessions

The portal uses the signed-in Omen account to list, create, and revoke API keys. Keys are stored against that account's user identifier.

Programmatic login

Native clients can use the documented native auth routes for login, refresh, logout, and MFA flows without browser cookies.

Gateway authentication

Authenticated gateways validate API keys server-side. Client systems present the key during the gateway authentication step and never inspect token hashes.

Step-up requirements

Creating keys with `trade` or `withdraw` permission requires a stepped-up session. Read-only keys can be created with current password verification.

OpenAPI referencev3.0.0Auth

Omen Auth API

Authentication and identity service for the Omen platform. Provides email OTP, password, passkey (WebAuthn), and OAuth (Google/Apple) login flows, JWT token management with rotating refresh tokens, wallet linking, API token generation, product selection with geoblocking, and a JWKS endpoint for downstream signature verification. ## Base URL | Environment | URL | |-------------|-----| | Local dev | `http://localhost:3

Environment endpoints

Local devhttp://localhost:3100Local dev

Authentication

bearerAuthhttpbearer

JWT access token issued by omen-auth.

cookieAuthapiKeyrefresh_token

HttpOnly refresh token cookie set by omen-auth.

Endpoints

Method	Path	Summary	Tags
GET	/health	Health check	Tokens
POST	/auth/otp/request	Request OTP code	OTP
POST	/auth/otp/verify	Verify OTP and get tokens	OTP
POST	/auth/password/signup/request	Request first-password setup code	Password
POST	/auth/password/signup	Add password to verified account	Password
POST	/auth/password/login	Log in with password	Password
POST	/auth/password/reset/request	Request password reset code	Password
POST	/auth/password/reset/confirm	Confirm password reset	Password
POST	/auth/username/signup	Sign up with username and password	Password
POST	/auth/username/login	Log in with username and password	Password
POST	/auth/passkey/register/begin	Begin passkey registration	Passkey
POST	/auth/passkey/register/complete	Complete passkey registration	Passkey
POST	/auth/passkey/login/begin	Begin passkey login	Passkey
POST	/auth/passkey/login/complete	Complete passkey login	Passkey
POST	/auth/oauth/google	Google OAuth login	OAuth
POST	/auth/oauth/apple	Apple OAuth login	OAuth
POST	/auth/refresh	Rotate refresh token	Tokens
POST	/auth/logout	Logout (revoke session)	Tokens
GET	/auth/me	Get current user	Tokens
GET	/auth/username/available	Check username availability	User
PATCH	/auth/me/username	Update username	User
POST	/auth/wallet/link	Link EVM wallet	Wallet
DELETE	/auth/wallet/link	Unlink wallet	Wallet
GET	/auth/wallet	Get linked wallet	Wallet
POST	/auth/email/request	Request email verification code	User
POST	/auth/email/confirm	Verify code and link email to account	User
POST	/auth/api-tokens	Create API token	API Tokens
GET	/auth/api-tokens	List API tokens	API Tokens
DELETE	/auth/api-tokens/{id}	Revoke API token	API Tokens
GET	/auth/products	List available products	Products
POST	/auth/products	Set active product	Products
POST	/auth/mfa/totp/enroll	Begin TOTP enrollment from an aal3 session	MFA
POST	/auth/mfa/totp/enroll/password	Begin TOTP enrollment with password step-up	MFA
POST	/auth/mfa/totp/enroll/oauth/google	Begin TOTP enrollment with Google step-up	MFA
POST	/auth/mfa/totp/enroll/oauth/apple	Begin TOTP enrollment with Apple step-up	MFA
POST	/auth/mfa/totp/confirm	Confirm TOTP enrollment	MFA
DELETE	/auth/mfa/totp	Disable MFA	MFA
DELETE	/auth/passkey/{id}	Delete a passkey credential	Passkey
POST	/auth/mfa/verify	Verify TOTP code (login flow)	MFA
POST	/auth/mfa/recovery	Use recovery code (login flow)	MFA
POST	/auth/mfa/step-up	Step-up to AAL2	MFA
GET	/auth/mfa/status	Get MFA enrollment status	MFA
POST	/auth/mfa/recovery-codes/regenerate	Generate or regenerate recovery codes	MFA
POST	/auth/recovery/login	Log in with a recovery code	MFA
GET	/auth/intercom/session	Get Intercom identity verification token	Intercom
GET	/auth/analytics/token	Get analytics verification token	Analytics
GET	/.well-known/jwks.json	JSON Web Key Set	JWKS
POST	/auth/native/otp/request	Request OTP code (native)	Native
POST	/auth/native/otp/verify	Verify OTP and get tokens (native)	Native
POST	/auth/native/password/signup/request	Request first-password setup code (native)	Native
POST	/auth/native/password/signup	Add password to verified account (native)	Native
POST	/auth/native/password/login	Log in with password (native)	Native
POST	/auth/native/username/signup	Sign up with username and password (native)	Native
POST	/auth/native/username/login	Log in with username and password (native)	Native
POST	/auth/native/password/reset/request	Request password reset code (native)	Native
POST	/auth/native/password/reset/confirm	Confirm password reset (native)	Native
POST	/auth/native/oauth/google	Google OAuth login (native)	Native
POST	/auth/native/oauth/apple	Apple OAuth login (native)	Native
POST	/auth/native/passkey/login/begin	Begin passkey login (native)	Native
POST	/auth/native/passkey/login/complete	Complete passkey login (native)	Native
POST	/auth/native/refresh	Rotate refresh token (native)	Native
POST	/auth/native/logout	Logout (native)	Native
POST	/auth/native/mfa/verify	Verify TOTP code (native)	Native
POST	/auth/native/mfa/recovery	Use recovery code (native)	Native
POST	/auth/native/mfa/step-up	Step-up to AAL2 (native)	Native
POST	/auth/native/recovery/login	Log in with a recovery code (native)	Native

Data models

ErrorTokenResponseNativeTokenResponseRefreshTokenBodyMessageResponseOtpRequestBodyOtpVerifyBodyPasswordSignupRequestBodyPasswordSignupBodyPasswordLoginBodyUsernameSignupBodyUsernameLoginBodyPasswordResetRequestBodyPasswordResetConfirmBodyPasskeyLoginBeginBodyPasskeyRegisterCompleteBodyPasskeyLoginCompleteBodyGoogleOAuthBodyAppleOAuthBodyUserInfoWalletLinkRequestWalletLinkResponseWalletGetResponseCreateApiTokenBodyApiTokenApiTokenCreatedSetProductBodyProductsResponseJwksResponseMfaRequiredResponseMfaVerifyBodyMfaRecoveryBodyMfaCodeBodyMfaEnrollPasswordBodyMfaConfirmBodyMfaEnrollResponseMfaConfirmResponseMfaStatusResponse