Skip to content

Authentication Guide

Every request to the Octamile AIMS API must include your credentials. There are no API keys in headers — authentication happens inside the request body via a userInfo object.

Your Credentials

When Octamile onboards you as a partner, you receive three values:

Credential Field Format Description
Partner ID userInfo.id UUID v4 Your unique partner identifier
Authorization ID userInfo.athrzt.id UUID v4 Your authorization ID
Authorization Key userInfo.athrzt.key Base64 string Your authorization secret key

ID format: Both userInfo.id and userInfo.athrzt.id are UUID v4 — the standard 8-4-4-4-12 hyphenated format, e.g. ac346b72-e8fe-4677-b9e2-dc6a763fba82. The API also accepts the 32-character hex form without hyphens (ac346b72e8fe4677b9e2dc6a763fba82), but the value must be a valid UUID v4 either way. Random 32-character alphanumeric strings that are not valid UUIDs will be rejected with a "55" error.

Keep these values secure. Never expose them in client-side code, logs, or version control.

Test vs Live Keys

Your authorization key determines which environment your requests run in — the key itself sets the mode, so you never have to pass an extra flag or flip a setting per request. This works the same way as test/live keys on payment platforms like Stripe or Paystack.

Key type Environment What happens
Test key Sandbox Policies auto-approve instantly. Nothing is sent to a real insurer. No policy is created and nothing is billed. Safe for dummy data.
Live key Production Requests are routed to real insurers. Real, billable policies are issued against live consumer data.

Point your sandbox integration at your test key and your production integration at your live key — typically by storing each in a separate environment (e.g. staging vs production):

# Sandbox / staging
OCTAMILE_AUTH_KEY=YOUR_TEST_AUTH_KEY

# Production
OCTAMILE_AUTH_KEY=YOUR_LIVE_AUTH_KEY

How to tell them apart: each key is labelled Test or Live where it is issued in the Partner Dashboard. Treat the label as authoritative — the environment a request runs in is decided by the key you send, not by any per-request field.

Existing single-key partners: if you were issued a single key before test/live keys existed, that key is unpinned and keeps its current behaviour — its environment follows the environment toggle on your Partner Dashboard. Your integration is unchanged. See the Going Live guide for details.

How to Authenticate

Include a userInfo object at the top level of every request body:

{
  "userInfo": {
    "id": "YOUR_PARTNER_ID",
    "athrzt": {
      "id": "YOUR_AUTHORIZATION_ID",
      "key": "YOUR_AUTHORIZATION_KEY"
    }
  },
  "cmmnd": {
    "cmmnd": "...",
    "seed": {}
  }
}

There are no Authorization headers, bearer tokens, or API keys. The userInfo block is the only authentication mechanism.

Complete cURL Example

curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "YOUR_PARTNER_ID",
      "athrzt": {
        "id": "YOUR_AUTHORIZATION_ID",
        "key": "YOUR_AUTHORIZATION_KEY"
      }
    },
    "cmmnd": {
      "cmmnd": "dump ipck_vhcl-tprt-1111*PRMM",
      "seed": {
        "insrncDrtn": "1y"
      }
    }
  }'

A successful authentication returns HTTP 200 with exctnFdbck.id set to 75.

Authentication Errors

The API always returns HTTP 200. Authentication failures are indicated in the response body:

exctnFdbck.id Meaning Fix
55 API error — often a bad credential Verify your id, athrzt.id, and athrzt.key values exactly match what Octamile provided
35 API at capacity Retry after a short delay (see Retry Guidance)

If you receive 55 on every request, check: 1. Your credentials contain no extra spaces or line breaks 2. You are sending Content-Type: application/json 3. The request body is valid JSON — use a JSON validator if unsure

Retry Guidance

A "35" response means the API is temporarily at capacity. It does not mean your request was rejected. Implement an exponential backoff:

  • Wait 2 seconds, retry
  • Wait 4 seconds, retry
  • Wait 8 seconds, retry
  • After 3 retries, surface an error to the user and try again later

Do not retry a "55" response without fixing the underlying issue first.

Storing Credentials Securely

Use environment variables — never hardcode credentials in source code:

Node.js 

const userInfo = {
  id: process.env.OCTAMILE_PARTNER_ID,
  athrzt: {
    id: process.env.OCTAMILE_AUTH_ID,
    key: process.env.OCTAMILE_AUTH_KEY
  }
};

Python 

import os

user_info = {
    "id": os.environ["OCTAMILE_PARTNER_ID"],
    "athrzt": {
        "id": os.environ["OCTAMILE_AUTH_ID"],
        "key": os.environ["OCTAMILE_AUTH_KEY"]
    }
}

Next Steps