Authentication

The Polymath API uses OAuth 2.0 client credentials for server-to-server authentication. Your application exchanges a client ID and client secret for an access token, then sends that token with each API request.

Use this flow for backend services, scheduled automation, CI jobs, and command-line tools running in a trusted environment.

Keep the client secret private

Do not use client credentials in browser applications, mobile applications, or other software where users can inspect the secret. Contact Polymath Support if you need a different authentication flow.

Get API client credentials

Polymath will issue your integration:

• A client ID
• A client secret

If you do not have credentials, contact your Polymath representative or email [email protected].

Store the credentials in a secret manager or another secure server-side store. Do not commit them to source control or write them to logs.

Authentication flow

Send a POST request to the token endpoint:

https://api.polymathrobotics.dev/oauth/token

Set the request's Content-Type header to application/json and send this JSON body:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

A successful response has this form:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 86399
}

expires_in is the token's remaining lifetime in seconds when the response is returned. A newly issued token is valid for about 24 hours, but the token endpoint may return an existing valid token, so the value can be less than 86,400 seconds. Always calculate renewal from the returned value.

Send the access token with each API request using the Authorization header:

Authorization: Bearer <access_token>

Using and renewing access tokens

• Cache and reuse the access token. Do not request a token before every API call.
• Calculate the expiry time from expires_in when you receive the response. Request another token about five minutes before it expires.
• The client-credentials flow does not issue a refresh token. Call /oauth/token again when you need another access token.
• The token endpoint may return the same token while it remains valid. Do not assume every response contains a new token.
• If an API request returns 401 Unauthorized, request a token and retry the API request once. If it still fails, check the credentials or contact Polymath Support.
• A 403 Forbidden response means the token is valid but is not allowed to perform the operation. Requesting another token will not change that permission.

Access and current limits

• Access applies across your account rather than to individual vehicles. Per-vehicle API client restrictions are not currently supported.
• Polymath configures the client's permissions. A token request cannot broaden or narrow those permissions.

If credentials or an access token are exposed, contact Polymath Support.

Token endpoint errors

Status	Error	What to do
400	invalid_request	Check that the request is correctly encoded and includes both credentials.
401	invalid_client	Check the client ID and secret. The client may also be disabled. Do not retry until the credentials are corrected.
503	temporarily_unavailable	Retry with bounded exponential backoff and jitter.

Request a token

Set your credentials as environment variables before running an example:

export POLYMATH_CLIENT_ID="your_client_id"
export POLYMATH_CLIENT_SECRET="your_client_secret"

curl

Requires curl and jq.

POLYMATH_TOKEN_RESPONSE="$(
  curl --silent --show-error --fail-with-body \
    --request POST \
    --url https://api.polymathrobotics.dev/oauth/token \
    --header 'Content-Type: application/json' \
    --data @- <<JSON
{
  "client_id": "$POLYMATH_CLIENT_ID",
  "client_secret": "$POLYMATH_CLIENT_SECRET",
  "grant_type": "client_credentials"
}
JSON
)"

POLYMATH_ACCESS_TOKEN="$(
  printf '%s' "$POLYMATH_TOKEN_RESPONSE" | jq -er '.access_token'
)"
export POLYMATH_ACCESS_TOKEN

Python

Requires the requests package.

import os

import requests

response = requests.post(
    "https://api.polymathrobotics.dev/oauth/token",
    json={
        "client_id": os.environ["POLYMATH_CLIENT_ID"],
        "client_secret": os.environ["POLYMATH_CLIENT_SECRET"],
        "grant_type": "client_credentials",
    },
    timeout=30,
)
response.raise_for_status()

token = response.json()
access_token = token["access_token"]
expires_in = token["expires_in"]

Node.js

const response = await fetch(
  "https://api.polymathrobotics.dev/oauth/token",
  {
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({
      client_id: process.env.POLYMATH_CLIENT_ID,
      client_secret: process.env.POLYMATH_CLIENT_SECRET,
      grant_type: "client_credentials",
    }),
  },
);

if (!response.ok) {
  throw new Error("Token request failed with status " + response.status);
}

const token = await response.json();
const accessToken = token.access_token;
const expiresIn = token.expires_in;

Continue to First Steps to use the token in your first API requests.