OAuth Credentials and API Authentication

OAuth 2.0 authentication gives integrated insurance carriers a stronger way to authenticate Public API integrations in Hi Marley. System Admins can create and manage OAuth credentials in Hi Marley, then use a Client ID and Client Secret to retrieve a Bearer token for Public API requests. This is an alternative to API key-based authentication and is intended for teams with active or planned Public API integrations.

Access requirements

• You must be a System Admin in Hi Marley to manage OAuth credentials.
• Your organization must use Hi Marley Public API integrations.
• Your technical team must have access to the integration service or application that will request and use the OAuth token.

What it looks like

To manage your OAuth Credentials, System Admins can navigate to Admin > Organization > Security and then select "OAuth Credentials". 

Within OAuth Credentials, you'll see your existing credentials which you can manage within Hi Marley, or you can add new clients. 

Before you begin

Work with your internal IT or integration team before making authentication changes. They will need to update the system that calls Hi Marley APIs so it can request, cache, and send OAuth Bearer tokens.

OAuth credentials are available in Hi Marley under:

Admin > Organization > Security > OAuth Credentials

How OAuth authentication works

Hi Marley supports OAuth 2.0 authentication for Public API integrations using the client_credentials flow.

Item	Description
Client ID	A unique identifier for the integration credential.
Client Secret	A secure value used with the Client ID to request an access token.
Bearer token	The access token returned by the Hi Marley OAuth token endpoint.
Token expiration	Tokens are valid for 1 hour and should be cached and reused until they expire.
Authorization header	Public API requests should include the token in the format: Authorization: Bearer <token>

Create or manage OAuth credentials

1. Log in to Hi Marley as a System Admin.
2. Go to Admin.
3. Select Organization.
4. Select Security.
5. Open OAuth Credentials.
6. Create or view the OAuth credential your integration will use.
7. Copy the Client ID and securely provide it to your integration team.
8. Copy or generate the Client Secret and store it securely according to your organization’s credential management policy.

Important

• Treat the Client Secret like a password. Do not share it in email, chat, tickets, or other unsecured locations.
• Only provide credentials to team members or systems that need them for the integration.
• If you believe a Client Secret has been exposed, work with your System Admin and Hi Marley team to rotate or replace the credential.

Request a Bearer token

After the Client ID and Client Secret are configured, your integration should request an access token from the Hi Marley OAuth token endpoint.

The request should use the client_credentials grant type and include the Client ID and Client Secret.

Example token request

POST <Hi Marley OAuth token endpoint>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<client_id>
&client_secret=<client_secret>

Example token response

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 3600
}

The access token is valid for 1 hour. Your integration should cache and reuse the token until it expires, then request a new one.

Use the Bearer token on Public API requests

After your integration retrieves a token, include it in the Authorization header for Hi Marley Public API requests.

Example API request header

Authorization: Bearer <token>

Do not send the Client ID or Client Secret on each Public API request. They should only be used to request a Bearer token from the OAuth token endpoint.

Recommended implementation steps

1. Create OAuth credentials in Hi Marley UAT.
2. Update your integration to request a Bearer token using the Client ID and Client Secret.
3. Confirm the integration sends the token in the Authorization: Bearer <token> header.
4. Validate that API requests complete successfully in UAT.
5. Confirm your integration caches and reuses the token until it expires.
6. Repeat credential setup and validation in Production.
7. After Production validation is complete, transition the integration from Basic Auth or API key-based authentication according to your organization’s rollout plan.

Best practices

• Cache tokens until expiration: Tokens are valid for 1 hour. Avoid requesting a new token for every API call.
• Store secrets securely: Use your organization’s approved secrets manager or secure credential storage process.
• Limit access: Only admins and integration services that require access should have the Client Secret.
• Validate in UAT first: Confirm your integration works as expected before updating Production authentication.
• Plan for credential rotation: Keep an internal process for replacing credentials when required by your security policies.

Frequently asked questions

Who can manage OAuth credentials?

System Admins can manage OAuth credentials from Admin > Organization > Security > OAuth Credentials.

What OAuth flow does Hi Marley support?

Hi Marley supports OAuth 2.0 authentication for Public API integrations using the client_credentials flow.

How long are tokens valid?

Bearer tokens are valid for 1 hour. Your integration should cache and reuse the token until it expires.

Where do I send the token?

Send the token in the Authorization header on Public API requests using this format:

Authorization: Bearer <token>

Is OAuth replacing Basic Auth or API key authentication?

OAuth provides a stronger authentication option for Public API integrations. Before transitioning from an existing authentication method, validate your integration in UAT and coordinate the Production rollout with your technical team.

What should I do if a Client Secret is exposed?

Treat an exposed Client Secret like a compromised password. Notify your internal security or integration team, stop using the exposed secret, and work with your System Admin and Hi Marley team to rotate or replace the credential.

Troubleshooting

The token request is failing

• Confirm the Client ID and Client Secret are correct.
• Confirm the request is using the client_credentials grant type.
• Confirm the request is being sent to the correct Hi Marley OAuth token endpoint for the environment you are using.
• Confirm the credentials were created in the same environment where the token request is being made.

API requests are returning unauthorized errors

• Confirm the request includes the Authorization header.
• Confirm the header uses the format Authorization: Bearer <token>.
• Confirm the token has not expired.
• Request a new token and retry the API request.

The integration works in UAT but not Production

• Confirm Production OAuth credentials were created in Hi Marley.
• Confirm the integration is using the Production Client ID, Client Secret, token endpoint, and API endpoint.
• Do not reuse UAT credentials in Production.