Getting Started
We heard you!
Welcome to the Enterprise Technology Organization (ETO) API Portal. We are working to improve the documentation and usability of our APIs to improve the API experience of our ETO Developer Community and Health Plan Partners.
Common Principles
ETO APIs feature a common set of principles:
• ALL APIs either produced or consumed by our Enterprise must be properly cataloged and proxied by our API Management Platforms.
• ETO APIs in this API Catalog follow the REST architectural style.
• Our standard media type is JSON, though some legacy APIs only support XML.
• Our standard security pattern for business and health plan partners is OAuth 2.0 with JSON Web Tokens (JWT). Mutual SSL over TLS is supported for plans that are not quite ready for OAuth 2.0.
• You will commonly see HTTP POST for read-only operations where a GET may seem more appropriate. This is by design to hide sensitive customer data in the message body rather than being visible in the URL.
• We follow standard HTTP response codes.
• Every REST API available in this catalog has a downloadable Open API Specification (OAS).
API Security
Security patterns vary between internal and external API traffic, with support for custom header injection at the API Gateway (GW) layer.
- The core security pattern for internal API traffic is API key.
- OAuth 2.0 using JSON Web Tokens (JWT) is the preferred security implementation for external API traffic. JWT is commonly referred to as "jot."
- ETO API Developers may use available security policies to inject common headers for backend implementations.
ETO Developers may find more information in the API Security Decision Matrix.
API Key
API Keys are required by on-premise ETO Apps for visibility into API consumption patterns and analytics.
Header Syntax: | Example: |
| x-hmhs-keyId: 26347190-9a87-4569-af04-37c650aee7b |
Obtaining an API Key
- API Keys are created at an application-scope in API Manager.
- Applications in API Manager represent ETO Products.
- Developers may create their own Application and API Key by following best practices.
- See this document on the API Management COP for more details.
Sample Request:
curl --location --request GET 'https://apiintqa.hmhs.com/api/v1/hello-world' \
--header 'Accept: application/json' \
--header 'x-hmhs-keyId: 26347190-9a87-4569-af04-37c650aee7b'
OAuth 2.0 and JWT
Below is a typical flow of OAuth 2.0 using JSON Web Tokens (JWT), the preferred security pattern for external API traffic.
Sample OAuth 2.0 Flow of Client Credentials and Resource Owner Credentials
Obtaining a Client ID and Secret
Follow these guidelines to obtain a Client ID and Secret (TODO: insert content).
Supported OAuth 2.0 Grant Types
OAuth 2.0 Grant Type | Use When... |
Resource Owner Credentials | Obtain an OAM OAuth access token with Token API v2 utilizing the resource owner’s username and password. Clients must capable of obtaining the Resource Owner's user Id and password credentials, typically using an interactive form or UI. Useful to obtain an access token in the context of a user, such as user login. This flow is also known as username-password authentication flow. |
Client Credentials | Clients request an access token using client Id and secret. Used outside the context or a user, or at an application client scope. Also known as the 2-legged OAuth flow. |
Authorization Code | The Authorization Code flow is suitable for OAuth clients that can interact with the resource owner’s user-agent (i.e., a browser), and that can receive incoming requests from the OAuth 2.0 authorization server. This flow works well for web server based OAuth clients. In this flow after the resource owner approves access, the web server OAuth client receives a callback with an authorization code and passes the auth code back to the OAuth 2.0 server to obtain an access token response. This flow is commonly referred to as 3-legged OAuth flow. |
Access Token via OAM IdP-Federation | OAM acts as Identity Provider to a partner application's service provider. On successful federation a JWT access token is shared with partner application as a SAML response. The typical use case is SSO integration between two parties. |
Extension Grant type | OAuth Services accepts third-party (non-Oracle) JWT assertions. This requires configuring a trust relationship by adding the third-party's certificate into the OAuth Services Service Profile keystore. OAuth Services use the keystore to verify the JWT assertion's digital signature. |
Obtaining a Token
Use the sample below to obtain a JWT from Token API v2. The Basic Auth header contains base64 encoded clientId and secret values.
Request:
curl --location --request POST 'https://oauthqa.hmhs.com/api/oauth/v2/oauthservice/tokens' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ZG9udC1iZS1hLWhhY2tlci1jbGllbnQ6ZG9uJ3QtYmUtYS1oYWNrZXItc2VjcmV0' \
--data-urlencode 'grant_type=client_credentials'Response:
{
"oracle_client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"expires_in": 900,
"token_type": "Bearer",
"oracle_tk_context": "client_assertion",
"access_token": "…………………………………"
}
Token Expiry
OAM OAuth profiles have a default token expiry shown below. These settings are configurable to align with session timeout.
Refresh Tokens are not recommended in scenarios where external login is enabled for a specific application.
Token Name | Grant Type | Expiration | Refresh Token |
| Authorization Code | code | 15 | N |
| Client Assertion | client_credentials | 60 | N |
| User Assertion | password | 60 | N |
See OAuth 2.0 detailed flows and sequence diagrams to learn more.