How to request API credentials from a carrier

Requesting API credentials from a carrier

This guide explains step by step how to request API access credentials from ocean carriers (Maersk, CMA CGM, COSCO, Hapag-Lloyd, etc.) and similar external systems, and how to register them in heyAtlas.

1. When do you need them?

heyAtlas tools such as rate lookup, container/vessel tracking, tariff retrieval and booking connect to the carrier's API on behalf of your company. This connection requires the API credentials the carrier issues specifically to you. Without credentials the related tools cannot run, and the assistant will ask you for connection details.

2. Who to ask and how

• Your first contact is your company's account representative or sales representative at the carrier.
• At most large carriers the request is forwarded to the integration/IT team through your representative.
• State in your request: the use case (e.g. rate query, container tracking), the environment you need (test/production) and your customer code.

Copy-paste request email template

Subject: API / integration access request — [Company Name], customer no: [XXXX]

>

Hello,

>

At [Company Name] we run our operations through our digital assistant. Could you please share the API access credentials allocated to us (username / API key, endpoint URLs, and customer code if applicable)? Our use case: [rate lookup / container tracking / booking]. We would like the test environment details first, and production credentials after validation.

>

Please share passwords and keys over a secure channel rather than in the email body.

>

Thank you.

3. What to ask for

| Item | Notes | | --- | --- | | API username / Client ID | The login identity | | API password / key / Client Secret | Secret value — must be shared over a secure channel | | Endpoint URL | Test and production addresses may differ | | Customer code | Mandatory at some carriers | | Environment | Test (sandbox) or production | | IP restriction | If the carrier enforces an IP allowlist, heyAtlas IPs must be added |

4. Carrier-specific tips

• Carriers with a self-service developer portal (e.g. Maersk, CMA CGM, Hapag-Lloyd): you can register on the carrier's developer portal on behalf of your company, create an application and generate your own key. Approval may take a few business days.
• Carriers with a manual process: a form is filled in via your representative; the integration team delivers the keys.
• You do not need to know which authentication type (API Key, OAuth2, etc.) each carrier uses; the heyAtlas system definition applies the right method automatically. Your job is simply to enter the details the carrier provides, completely.

5. Entering the details into heyAtlas

1. Open Settings → Credentials in the portal (company admin permission required).
2. Select the relevant system (carrier) and fill in the fields the carrier provided.
3. You can define multiple credentials for the same system and mark one as the default (e.g. different customer codes).
4. After saving, verify the connection by trying the related tool through the assistant.

See also: Managing credentials and System connections.

6. Security

• Avoid receiving passwords and keys as plain text in an email body; prefer a secure sharing link.
• heyAtlas stores credentials encrypted and never displays them as plain text on screen.
• If you suspect a leak, ask the carrier to rotate the key and update the new value in heyAtlas.
• See also: Credential security.

7. Common issues

• 401 / 403 errors: the password may be mistyped, expired, or the account not yet activated. Re-enter the details; if it persists, have your representative verify them.
• Test / production mix-up: a test key will not work against the production endpoint (or vice versa). Check which environment's details were entered.
• "Access granted" but nothing works: some carriers activate API subscriptions per product (e.g. tracking only); ask which products your subscription covers.
• IP blocking: if the carrier enforces IP restrictions, the IP heyAtlas calls from must be allowlisted; you can request the IP details from our support team.

8. Getting help

If the process stalls, open a support ticket via Support → My Tickets; just state which carrier it is and at which step you are stuck.