Simple integration

How it works

Point your requests at https://movik.us/api/partner/ followed by any path from the reference, and send your Movik credentials as HTTP Basic auth. Movik authenticates you, obtains a token, calls the API on your behalf and returns the response unchanged.

You never see a token. There is no expiry to track, no refresh to schedule and no cached state in your application — which means there is no token lifecycle bug waiting for you at the one-hour mark.

curl -u 'you@example.com:your-password' \
  https://movik.us/api/partner/fmcsa/carrier/3215521

Every HTTP client has Basic auth built in, so there is nothing to hand-roll: -u in curl, auth= in Python requests, CURLOPT_USERPWD in PHP.

Performance

Authenticating on every request does not mean paying for it on every request. Movik caches the token it mints for you server-side and reuses it until it nears expiry, so the underlying exchange — around 370ms — runs roughly once an hour rather than on each call. Requests in between add only the proxy hop.

The x-movik-token-minted response header tells you which happened: 1 if that request performed an exchange, 0 if it reused a cached token. Useful when you are timing a bulk run and want to know whether an outlier was authentication.

Client examples

// No token handling. No refresh logic. No cached state.
const EMAIL = process.env.MOVIK_EMAIL
const PASSWORD = process.env.MOVIK_PASSWORD
const BASE = 'https://movik.us/api/partner'

const auth = 'Basic ' + Buffer.from(`${EMAIL}:${PASSWORD}`).toString('base64')

export async function movik(path, options = {}) {
  return fetch(`${BASE}${path}`, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: auth,
      'Content-Type': 'application/json',
    },
  })
}

// Usage
const res = await movik('/fmcsa/carrier/3215521')
const carrier = await res.json()

import os, requests
from requests.auth import HTTPBasicAuth

BASE = "https://movik.us/api/partner"
AUTH = HTTPBasicAuth(os.environ["MOVIK_EMAIL"], os.environ["MOVIK_PASSWORD"])

def movik(method, path, **kwargs):
    return requests.request(method, f"{BASE}{path}", auth=AUTH, timeout=60, **kwargs)

# Usage
carrier = movik("GET", "/fmcsa/carrier/3215521").json()

<?php
$email = getenv('MOVIK_EMAIL');
$password = getenv('MOVIK_PASSWORD');

$ch = curl_init('https://movik.us/api/partner/fmcsa/carrier/3215521');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, "$email:$password");
$carrier = json_decode(curl_exec($ch), true);
curl_close($ch);

Writing data

Bodies, query strings and content types pass through untouched. A POST looks exactly like the reference describes it, with credentials attached:

curl -u 'you@example.com:your-password' \
  -X POST https://movik.us/api/partner/signup/check-dot \
  -H 'Content-Type: application/json' \
  -d '{"dotNumber": "3215521"}'

Note the method matters. Routes are matched on method and path, so sending GET to a POST route returns 404 unknown_route rather than a method error. The reference shows the method for every endpoint.

What you can reach

Your credentials are registered for specific API domains, and the proxy enforces that. A request to a domain outside your registration returns 403 out_of_scope with the list of domains you may use:

{
  "error": "out_of_scope",
  "message": "Your credentials are not authorized for the Bank Accounts domain.",
  "authorized_scopes": ["Signup", "Organization", "User", "Debtors", "FMCSA"]
}

If you need a domain that is not listed, ask — it is a registry change on our side, not a code change on yours.

Errors

Responses from the API itself pass through with their original status and body, so a 400 from a validation failure reads exactly as the reference describes.

Keeping credentials safe

Because credentials travel on every request, treat them accordingly: keep them in your secret manager rather than in source, never log the Authorization header, and use HTTPS only — plaintext requests are refused rather than redirected. If you need them rotated, ask and we will reissue.

Prefer to hold a token yourself instead? The token-based flow is also supported and sends your password once an hour rather than on each call.