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.

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