Connecting to OMD

Optimize My Day provides a REST-based API, with which you can:

  • upload data to OMD
  • download data from OMD
  • call OMD business functions

The supported authentication methods are:

OAuth 2.0 Authentication

OMD supports OAuth 2.0, a secure and widely adopted authorization framework that enables trusted access to resources without exposing user credentials. We implement two primary OAuth 2.0 flows: Server-to-Server Authentication and Web-Based Authentication, ensuring both automation and user interactivity where appropriate.

Server-to-Server Authentication (Client Credentials Grant)

For backend integrations and automated services, we use the Client Credentials Grant flow. In this scenario, the client (e.g. an application or service) authenticates directly with the authorization server using its client ID and secret. This allows secure, token-based access to protected APIs without user involvement.

Key characteristics:

  • Suitable for machine-to-machine communication
  • No user interaction required
  • Access tokens are short-lived and securely managed
  • Ideal for background jobs, service daemons, and API integrations

Web-Based Authentication (Authorization Code Flow with PKCE)

For user-facing web and mobile applications, we implement the Authorization Code Flow, enhanced with Proof Key for Code Exchange (PKCE) for additional security. This flow involves redirecting users to the authorization server for login and consent, after which a secure authorization code is exchanged for an access token.

Key characteristics:

  • Secure and user-centric
  • Supports third-party identity providers (e.g. Google, Microsoft)
  • Enables Single Sign-On (SSO) and federated identity
  • Refresh tokens can be used to maintain long-term sessions

OpenID Connect Support

OMD's OAuth 2.0 implementation is extended with OpenID Connect (OIDC), providing an identity layer on top of the OAuth 2.0 protocol. This allows applications to:

  • Obtain User Information: Retrieve user profile information in a standardized manner
  • Single Sign-On (SSO): Facilitate seamless user experiences across multiple applications through SSO capabilities.
  • Enhanced Security: Leverage ID tokens for verifying the identity of end-users.

Endpoint Discovery

To streamline integration and ensure compatibility, OMD provides a discovery document adhering to the OpenID Connect Discovery specification. This document, available at OMD OAuth 2.0 Discovery Endpoint, contains metadata about the OAuth 2.0 implementation, including:

  • Authorization Endpoint: URL for initiating the authorization flow.
  • Token Endpoint: URL for exchanging authorization codes or client credentials for access tokens.
  • Supported Scopes: List of scopes that can be requested during authorization.
  • Token Signing Algorithms: Information about the algorithms used to sign tokens.

Example Server-to-Server Authentication

You need the following credentials from your OMD consultant:

  • YOUR_CLIENT_ID
  • YOUR_CLIENT_SECRET
curl -X POST "https://www.optimizemyday.com/omd-auth/rest/v1/omd-oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=openid profile"

The response should look similar to the JSON string below:

{
  "access_token": "eyJraWQiOiJ...<snip>...nZg",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile"
}

Notes

  • The access token must be included as a Bearer token in the Authorization header of your API requests.
  • Replace openid profile with the actual scopes required for your API usage (check documentation or ask OMD support).
  • expires_in indicates how long (in seconds) the token is valid.

Example Authorization Code Flow with PKCE

Prerequisites

The authorization endpoint and token endpoint (from discovery document):

Step 1: Generate PKCE Code Verifier & Challenge

openssl rand -base64 32 | tr -d '=+/\\' | cut -c -64 > code_verifier.txt

Then hash the code_verifier with SHA-256 and base64-url encode it to create the code_challenge.

code_verifier=$(cat code_verifier.txt)
code_challenge=$(echo -n $code_verifier | openssl dgst -sha256 -binary | openssl base64 | tr -d '=' | tr '/+' '_-' | tr -d '\n')

Step 2: Redirect User to Authorization URL

https://www.optimizemyday.com/omd-auth/rest/v1/omd-oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=openid%20profile&code_challenge=$code_challenge&code_challenge_method=S256

This will prompt the user to log in and authorize access.

After login, they are redirected to:

https://yourapp.com/callback?code=AUTHORIZATION_CODE

Step 3: Exchange Authorization Code for Access Token

curl -X POST "https://www.optimizemyday.com/omd-auth/rest/v1/omd-oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=$(cat code_verifier.txt)"
Sample Successful Token Response
{
  "access_token": "eyJraWQiOiJ...<snip>...",
  "refresh_token": "def50200...<snip>...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "openid profile"
}
Notes
  • No client_secret is used in PKCE flow for public clients (browser/mobile apps).
  • Refresh tokens may be provided, depending on client configuration.
  • Always store tokens securely and renew access tokens before expiry.

BASIC Authentication (DEPRECATED)

To allow basic authentication, you will have to provide a Base64-encoded username/password header along with the HTTP request. SSL/TLS encryption on IP-transport level is required. If you intend to send a zipped XML document, add the zipped=true parameter to the URL.

results matching ""

    No results matching ""